Fourth Integrations: Glossary of Terms

Term

Description

Access Control

A security technique for determining who should have access to software, data, or locations.

Fourth offers an Identity and Access Control solution for customers that lets employees access Fourth without needing to assign a work email address to the employee. Additionally, we can act as the identity provider for other applications your employees may need to sign into.

Agile

A project management concept that is popular within software development. It values customer collaboration, adaption and iteration, and working software. Its intention is to ensure that customers are provided software that meets their needs quickly and is regularly updated.

Software houses that follow Agile often use SAFe, Scrum and Kanban as their framework.

API

An Application Programming Interface (API) provides a communication point into a software platform. Most software companies provide one or more APIs to give customers and partners access to their platform.

APIs are used to:

• Transfer data from a legacy platform into a new platform.

• Show data from another system; for example, a product supplier’s catalogue can be displayed in Fourth’s Inventory for Hotels.

• Allow other applications (or users) to view and manage data within a platform.

• Trigger actions within a platform. For example, requesting that the platform sends a Push notification to an end user.

APIs often restrict who can access any data and what actions (view, create, edit, trigger action, or delete) they can take. Users take these actions by making an API request. The platform will always respond with an API response that will either provide the requested data, confirm that an action has happened, or provide an error message.

Note that an API is hosted online by a server, while applications using an API are refered to as clients.

API credentials

The name and password, or token that is required to access an API. To use a Fourth API, you must have valid set of credentials for that API. For security, access to each API is set up independently and you may have differing credentials for each API you use.

Similarly, each partner connected to a Fourth API has a set of credentials unique to each customer and API instance.

API key

An identifier provided by a server (for example, the Fourth platform) to an application, so that the application can access a specific API. API keys offer an alternative option to using API credentials. However, API keys are not particularly secure, so are only used by a select range of Fourth APIs where this is not a concern.  

API Request

A message sent from a client to an API server.

API Response

A message sent from an API server to a client after receiving an API request.

Asynchronous process and response

An asynchronous process (or response) is where the server or client sends a new request linked to a previous one, normally to provide an outcome or status update for the initial request. For this to work, the server provides the client with an ID in the synchronous response. Then, either the:

• Client can query the outcome by sending the ID to the server in a new request.

• Server can send the outcome (when known) to the client. The server sends the same ID through so that the client knows which request it relates to.

Authentication method

How API credentials are used to authenticate with an API. There are two methods used by Fourth’s APIs: Basic Authentication and OAuth 2.0.

Basic Authentication

Basic authentication is a standard method to authenticate an API user (such as an application). When using Basic Authentication, the API credentials are sent inside the header of each API request.

Client

A computer or program that requests a service from another computer or program. For example, web browsers are clients that requests webpages from servers.

Connected App

A customer or partner web app that is integrated into the Fourth App experience. This lets employees:

• Open the app from a customisable icon within the Fourth App

• Use the app without needing to log into it separately

To check on publishing; any marketing page we can link out to here?

.csv file

A comma-separated values (.csv) file is a type of text file that can be used to send data between different platforms. It uses line breaks to separate a row of data, and commas to separate each data record; for example:

apples, 1kg, 1.00
oranges, 1.5kg, 1.50
pears, 1kg, 2.00

Data models and data mapping

A data model provides the framework for storing data in a sensible and ordered way. Each platform that holds data — such as information about people, recipes or ingredients — does so using a data model. Every platform uses its own data models.

Data mapping is the process of creating a mapping between the data models of two (or more) systems. This then allows organisations to:

• Share data between different platforms; e.g. you may need to perform data mapping as part of an API integration.

• Consolidate multiple databases into one database. This type of activity often happens when businesses merge.

• Migrate data from a legacy system to a new system.

Data migration

Data migration occurs when data is moved from a legacy platform to a new platform.

There may be multiple actions that need to happen as part of a data migration, including creating a data mapping, exporting the existing data out of the legacy platform, transforming the data using the mapping, and then importing the data into the new platform.

Endpoint

Each API has one or more endpoints. For web APIs, an endpoint is a URL that points to a specific “resource”, such as:

https://api.fourth.com/qai/oauth/connect/token

In this case, the above endpoint is where developers can get an authentication token. Endpoints are everywhere on the Internet; each page, image or other file on a website is a “resource”, and is available as a URL. For example, this URL is to a resource that happens to be an image:

https://upload.wikimedia.org/wikipedia/commons/a/af/Tux.png

When you click this URL (endpoint), your browser makes an HTTP “GET” request to the endpoint asking for the resource. It then displays the results — in this case, a delightful penguin picture.

Federated authentication

Federated authentication is another name for Single sign-on (SSO) often, but not exclusively, where external 3rd party systems are accessed.

Fourth uses this term to describe integrations between ourselves and other systems acting as the primary authentication providers. The most common third-party authentication providers are Active Directory and Okta.

This type of integration happens when a customer has an existing single sign-on solution. Once integrated, users can access Fourth using their existing corporate credentials.

Federation ID

Federation ID is a term used in single sign-on integrations, particularly Salesforce.

It is the identifier for an end user that two platforms agree to use. Single sign-on integrations often use the end user’s email address as the Federation ID. However, it can also be any other unique identifier for a person, such as their Fourth account ID, employee ID or mobile phone number.

Fourth Account ID

Each person who accesses Fourth — from your management team viewing Analytics, or your casual staff checking payslips through Engage — is provided with a Fourth Account. The unique identifier for these accounts is called a Fourth Account ID.

This is an 18-digit alphanumeric string, for example: 0058E00000207pP

FTP

File Transfer Protocol (FTP) is a protocol used to transfer files over any type of network such as the Internet. There are many FTP applications that users do this from their desktop, and software platforms can send FTP files programmatically.

Usernames and passwords used with this protocol are sent in plain text, so it is highly recommended to instead use SFTP, a type of FTP that encrypts credentials.

GET request

GET is a type of REST API method.

GET requests allow a client to get data from a server (e.g. the Fourth Platform). GET requests do not change the data stored on the server in anyway.

For example, you can use GET requests to retrieve data about ingredients, recipes and menus from Fourth Inventory for Restaurants.

Identity Provider

Identity provider is a term used in single sign-on integrations. It is the platform that authenticates end users on behalf of other applications.

Fourth acts as the identity provider for Connected Apps. If Federated Authentication is used then the Identity Provider may be a customer’s system.

Integration

An integration refers to connecting two separate systems together.

Some integrations unite systems closely, with lots of data passed between the two, such as when two businesses merge. However, many integrations are between two systems that benefit from sharing only some of their data or services; for example, between two separate businesses. APIs are a popular integration option for sending and receiving data between businesses.

JSON

This is a format for sending and receiving data. Like XML, it is often used by web APIs. JSON is intended to be both human and machine readable.

JSON uses symbols - [{ “:,}] - to separate and identify data. For example:

[
{
"firstName": "Sasha",
"lastName": "Mustermann"
}
]

Just-in-time user provisioning

Just-in-time (JIT) user provisioning is a term used in single sign-on integrations.

JIT provisioning allows a service provider to create a user account only when a user logs in for the first time to their application. The service provider relies on the identity provider (e.g. Fourth) to authenticate the user. In the authentication message, the service provider also provides enough details about the user to create an account.

By using JIT provisioning, service providers do not need to integrate with another API to get the basic user details they need to establish a user account. However, some service providers may choose to provision users separately, particularly if they need more indepth information about a user.

Metadata

Think of it as “Data about the data”.

Information (or properties) that describes a set of data, such as a webpage or file. Metadata is normally stored with the data. For example, .png files include metadata such as the title, author, creation time and copyright.

Metadata may also refer to data that regulates or configures a service. For example, during single sign-on integrations, both parties (service provider and identity provider) must give one another their metadata to establish a trusted connection. This metadata describes the capabilities and expectations each provider has.

Methods (REST)

Methods are the type of actions a REST API supports. The most common methods supported are GET, POST, PUT and DELETE. Each of these is for a type of action:

• GET — used to get data from a server

• POST and PUT — used to add or update data on the server

• DELETE — used to delete data from a server

A request to a REST API must include the method. This lets the server know what action is expected.

Native app

An application that has been developed to work on a specific device and operating system, such as an iPhone. Native apps are able to make full use of a device’s functionality, but cannot be installed on non-compatible devices, such as an Android phone. Once installed, native apps are normally accessed via an icon on a user’s phone screen.

OAuth, OAuth access token

OAuth is a standard method to authenticate an API user, such as a partner’s application. When using OAuth, the application sends their API credentials to the Fourth OAuth service. The service responds with a token. The application then sends this token in API requests to the desired API.

OAuth is more secure than Basic authentication. One resason is that the tokens are changed regularly. This means that anyone who intercepts and logs the messages between an application and an API cannot successfully use any tokens discovered. OAuth can also be implemented with a wider range of scenarios than Basic authentication.

Organisation ID

This term is used by Fourth in our UK Employee API documentation. It is an ID unique to each customer. Partners need this ID before they can make requests to the API.

Outbound federation

Outbound federation is a term used in single sign-on integrations.

It refers to integrations where Fourth authenticate users on behalf of our partners and customers.

All connected apps in Fourth Engage use outbound federation.

POST request

POST is a type of REST API method.

POST requests let clients:

• Send new data to a server

• Update data in the server

• Trigger an action

For example, an applicant tracking system can send Fourth a POST request with a new employee’s details.

Postman

Postman is a both a company and application name. The Postman application is popular for testing an API that you are integrating to. For example, a developer may use Postman at the start of development to send some initial API requests and view the responses sent back.

Push Notification

A type of message sent to a user’s mobile phone. Push notifications are linked to individual apps; for example, a user must have the Fourth App installed to receive push notifications from Fourth. Users can also choose whether or not to recieve push notifications for each app they have installed on their phone.

Connected Apps can send push notifications to Fourth users via our Notifications API.

PUT requests

PUT is a type of REST API method.

PUT requests let clients update data in the server or trigger an action.

For example, an HR system can send Fourth a PUT request to update an existing employee’s details.

Retry strategy or policy

Retry strategies are used between clients and servers when they cannot reach one another. For example, if a client sends a request to a server, but does not receive a response, then the client will retry the request. A retry strategy is the set of rules that the client or server will use to decide how often to retry a request, and how many times.

Normally connection issues between servers and clients are temporary, so using a retry strategy ensures that requests are eventually processed without needing to call Support.

For Fourth APIs, we ask that our partners and customers do not retry requests more than once a minute, and preferably use an exponential backoff with requests (e.g. 1 minute, 2 minutes, 4 minutes, 8 minutes, 16 minutes, 32 minutes).

REST / RESTful

Representational state transfer (REST) is a popular type of design for web APIs.

REST defines a set of guidelines that API developers can use to create a REST API. A REST API can support different types of actions, such as adding, updating, retrieving or deleting data, as well as triggering an action. These actions (or “methods”) have names such as GET, POST, PUT and DELETE.

Both XML and JSON are used to hold the data in a REST request.

Root URL

The base URL for a website or other resource. For example, www.fourth.com is the root URL for all pages on the Fourth website.

We do not list the root URLs for our APIS online. Instead, Fourth provides our customers and partners with these details when an integration occurs.

SAML

Security Assertion Markup Language (SAML) is a popular, standard way to provide single sign-on (SSO). Fourth offers SSO integrations using SAML version 2.0.

SAML assertion

This is an XML document that contains authentication details for an end user.

SAML assertions are created when a user either manages or fails to authenticate with an identity provider (such as Fourth). The identity provider sends the assertion to the service provider (such as a website) that had requested the user authentication. The assertion tells the service provider if the user was successfully authenticated and should therefore be allowed to use their service.

SCIM

System for Cross-domain Identity Management (SCIM) is a standard system for sharing user data, such as a person’s name and job title, between different software platforms.

SCIM’s primary purpose is to make it easy to share the user data needed to create user accounts. We provide the Fourth Account SCIM API to our connected partners for just this purpose.

Security certificate

Security certificates help make secure and trusted connections between different web servers and software. The certificate identifies a user, organisation, or hostname; and contains their public key.

Almost all security certificates use X.509 as the format for sending the certificate data, so both “security certificate” and “X.509 certificate” act as synonyms.

Server

A piece of computer hardware or software that provides services to clients. For example, each webpage on the Internet is hosted on a server. When a client (web browser) requests the webpage, the server sends the client the webpage data.

Service Provider (SAML)

Service provider is a term used in SAML 2.0 single sign-on integrations.

A service provider is an application, such as a website, that gets a SAML identity provider to authenticate users on its behalf.

For example, on the Fourth mobile app, our partners' connected apps are “service providers” while Fourth acts as the “identity provider”.

Scrum

Scrum is an Agile project management framework. Scrum is a popular framework for use in software development. In this framework:

• Work is broken into small chunks that can be completed within a “sprint”.

• Each sprint is normally 2 or 4 weeks.

• At the beginning of a sprint, the team plans what chunks of work they will do.

• During the sprint, team members meet daily for a short meeting to discuss any issues that have arisen

• At the end of a sprint, the work is reviewed by both the team and the product’s stakeholders.

SFTP

 SSH File Transfer Protocol (also known as Secure File Transfer Protocol) is a protocol used to transfer files over any type of network such as the Internet. There are many SFTP applications that users do this from their desktop, and software platforms can send SFTP files programmatically.

SFTP is a secure version of FTP. It is highly recommended to use SFTP rather than FTP for file transfers.

Single sign-on (SSO)

Single Sign-On (SSO) is an authentication solution that allows an end user to access multiple web applications using just the one set of credentials. This saves the user from needing to remember multiple usernames and passwords. And, once they have logged in, an end user can access other connected web apps without logging in again, until their authenticated session expires.

Fourth offers an SSO solution for customers and partners using SAML 2.0, a popular the industry standard for SSO integrations.

SOAP

SOAP stands for “Simple Object Access Protocol” and is a messaging protocol used by web services. A SOAP message has an “envelope”, “header” and “body”. SOAP uses XML as the message format; for example:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:m="http://www.example.org">
<soap:Header>
</soap:Header>
<soap:Body>
<m:CatName>Bob</m:CatName>
</soap:Body>
</soap:Envelope>

SOAP messages are normally sent using HTTP.

SOAP is not generally used for new integrations as REST APIs are easier to develop, read, and integrate with.

Spaghetti code

Spaghetti code refers to code that has been written in an adhoc and unstructured way and that does not follow standards or best practices. As the software code becomes more complex, it becomes harder for developers to understand or troubleshoot; and seems entangled and messy, like a bowl of spaghetti.

Submission

In integrations, a submission is a file that contains collated data, and is sent to a service via email, SFTP or other method. Once received, the file is then processed by the service.

Swagger

Swagger is the product name for a set of popular tools that let businesses create and display REST API documentation. Fourth uses the Swagger UI tool to provide API reference documentation for many of our APIs. This documentation is also found of the Fourth Developer Hub.

Note that Swagger tools can only read and display documentation that uses the OpenAPI specification. Many people mistakenly use the term “Swagger” to refer to both the tools and the specification.

Synchronous response

After making a web API request, a client must wait for a response from the server before closing the connection to the server. This is called a synchronous response.

Synchronous responses always provide a status for the request – for example, to confirm that the request was successful or unsuccessful. The response will also include any data requested. For example, whenever a browser successfully gets a webpage, the response includes a status code of “200 OK” and the response body includes the webpage data.

Web app

An application that runs on a web server. Web apps can be accessed by any device with web browser, including mobile phones. A web app cannot be downloaded to a user’s phone unlike a native phone app.

The benefit of web apps is that users can access them regardless of the operating system or device they are using. However, unlike native phone apps, web apps do not have access to a phone’s full functionality, and do not normally have an icon on the user’s phone.

For customers and partners with web apps, Fourth can include icons for these in the Fourth App. This makes your apps more visible to employees and creates a more unified user experience.

Web service

A software service that sends and receives data using web technologies such as HTTPS, Javascript, JSON, XML, REST and SOAP.

Web services allow programs on different networks and written in different programming languages (like C# or Java) to share data. By using standardised technologies, a web service is able to easily provide data and services to other applications.

Whitelist

A membership list where only members on the list can access a specified location, resource, data or other desired item. Whitelists can be used to restrict access to a server or software system.

In software, membership lists are normally made up of either users or IP addresses. For example, whitelists are often used to ensure only traffic from selected IP addresses are allowed through a firewall.

X.509 certificate

 X.509 is a standard format used to send “public key certificates”. These certificates help make secure and trusted connections between different web servers and software. The certificate identifies a user, organisation, or hostname; and contains their public key.

For example, HTTPS uses this standard to create a trusted connection between a browser and a web server. If you have ever receive a “certificate warning” when browsing the website, this is because there is a problem with the website’s X.509 certificate.

Certificates can come from a certificate authority, or alternatively businesses can “self-sign” certificates. You should only trust self-signed certificates from businesses you have an established relationship with.

Note that the term security certificate is often used as a synonym.

XML

XML is an acronym for “extensible markup language”. It is often used by web APIs to send and recieve data. XML is intended to be both human and machine readable.

XML looks similar to HTML, with tags inside “<“ and “>” symbols, for example:

<firstname>Sasha</firstname>
<lastname>Mustermann</lastname>

Not all APIs use XML for sending data; for example, some Fourth APIs only use JSON, a newer and more light-weight format.