Integrator management

What is an integrator? #

An integrator provides a standardized interface to enable efficient data management and API interactions that ensures that SCALAR DataHub APIs are accessible, dependable, and ready for integration into diverse data ecosystems. Through marketplace APIs, ZF offers professional services rendered by third parties to its customer organizations, as explained in the following sections.

Purpose #

Partners require access to data for processing, reporting, and analysis. Instead of onboarding them into an organization through the User management module, they can consume the required data (DataHub APIs) shared through integrators.

Types of integrators available on the SCALAR platform:

Marketplace: integrators configured by ZF SCALAR integration team and presented to their customers based on the most frequent use cases to service fleet operations. These integrators can be commonly accessed by all customers and form the basis on which partnerships are formed.
It is recommended that you explore the available marketplace integrators and leverage their benefits before configuring organization-specific integrators, thereby reducing the efforts.
Organization-specific: also referred to as internal integrators, an administrator can configure these integrators to cater to a specific requirement, such as inhouse integrations with other software.
Permission types can be configured by the customer organization. For more information, see how to manage permission types at the module level.
Access to APIs (permission types) are determined by the product subscription. An administrator can perform CRUD (create, read, update, and delete) operations on these integrators.

NOTE:

Explanation on machine integrators is not within the scope of this documentation.

Benefits of using integrators #

Besides the obvious benefit of monetizing your APIs, you can gain the following valuable insights into your consumer behavior through reports generated from API analytical tools, such as Google Analytics, Heap, AWS, and Matomo that trace and track API usage:

Interactions with your website and other applications for the module-specific APIs being consumed
Number of calls recorded or APIs consumption patterns

NOTE:

The DataHub portal provides visibility on API calls.

Marketplace integrators #

Based on regular SCALAR use cases, partners who provide value-added services or offerings in the supply chain and logistics industry are evaluated by the ZF integration team.
The respective integrators with DataHub APIs are then configured by classifying them as marketplace integrators and made available to the customers.

Partnership engagement #

SCALAR partners operate regionally as well as globally to provide specialized services, such as fleet management, fuel management, maintenance and diagnostics, insurance, and risk management. If a customer wants to establish partnership, they can go to the Marketplace tab, review partner information, and authorize ZF to share data with the selected partner through marketplace integrators.

NOTE:

The marketplace integrators listed on the tab are common to all customers.
The current UI implements a basic minimum functionality of activating partnership with partners for value-added services.

Establish partnership #

You can explore, evaluate, and choose to enter into a formal partnership with partners listed on the Marketplace tab to professional services being rendered by them.

On the Integrators page > click the Marketplace tab. The marketplace integrators are displayed.

NOTE:

Refer to the Activated column: Yes or No to verify whether the partnership is activated.

In the Name column, select an integrator link to view details of the partner and their service offerings. The integrator details page is displayed.
To enter into a partnership with a partner > click Activate. The Establish a new partnership dialog is displayed.
To authorize ZF to provide the partner access to the processed data, select the consent checkbox, and then click Establish. The partnership is activated for your organization.
The client ID and secret can now be viewed for the activated marketplace integrator, which can be shared with the respective partner or consumer.

You can modify the GDPR (General Data Protection Regulation) permission settings for integrators listed on the Marketplace tab.

NOTE:

The Marketplace tab provides limited control. On this tab, the customers can only view the partner details and edit GDPR permission settings.

On the Integrators page > click the Marketplace tab. The integrators or partners list is displayed.
Click the required integrator record. The selected integrator details page is displayed.
Click Edit GDPR. The Edit GDPR page is displayed.

NOTE:

By default, the permissions related to GDPR are selected.

If required, clear the checkboxes to remove restrictions related to GPS position and driver identification and to modify the number of days for sharing historical data.

NOTE:

The number of days for sharing historical data cannot exceed the retention period defined by your organization.

Edit a marketplace integrator #

You can modify marketplace integrator details, such as name, description, teams, module-wise API permission types, and select or clear the Mark as Master integrator checkbox.

On the Integrators page > click the Marketplace tab. The integrators or partners list is displayed.
Click the required integrator record. The selected integrator details page is displayed.
In the Integrator details section, modify details in the Name including Mark as Master integrator feature, Description, Teams, and Permission type sections, and then click Save. The integrator details are modified.

Deactivate a partnership #

You can discontinue a partnership engagement by deactivating the partnership.

On the Marketplace tab, select the integrator name link from the list. The integrator details page of the partner is displayed.
Click Deactivate. The Deactivate integrator dialog is displayed.
To confirm the action, click Deactivate.

A confirmation message is displayed indicating deactivation of the integrator. The partnership is deactivated and the data sharing with the partner company is stopped.

NOTE:

After deactivating the partnership, the customizations or changes made to the GDPR permission settings are reset to default permissions.

Organization-specific integrators #

You can configure and perform CRUD operations on organization-specific integrators.

Through this module, you can create an integrator, map it to multiple logically organized module-specific APIs, and manage permission types to provide access to module-wise APIs. A customer who is required to access the DataHub APIs can use their client ID and secret to generate a token for authentication to access the data.

NOTE:

Rate limit is applicable for token retrieval.

Add an integrator #

From the Integrators module, you can create an integrator specific to your organization and configure it by selecting the required DataHub APIs. These APIs correspond to different modules in SCALAR. You can manage permissions to module-specific APIs while adhering to the GDPR guidelines.

In the Admin module, from the left navigation pane, click Integrators . The Integrators page is displayed.
Click Add integrator. The Add integrator page is displayed.

Enter information in the various sections as explained in the table below, and then click Save.

Field	Action
Name	Assign a name for the integrator NOTE: The name must uniquely identify the integrator.
Name > Mark as Master Integrator	Select the Mark as Master integrator checkbox to provide the integrator access to all the resources, such as assets, drivers, and places, irrespective of their team affiliation. This image shows an example of a master integrator. If an integrator is marked as a master integrator, team-specific access assigned earlier will be overridden, and the master integrator will obtain full access to all the resources thereafter. If the Mark as Master integrator checkbox is not selected, the integrator’s access to resources will be determined by their team-specific permissions defined in the Teams section.
Description	Provide information about the integrator to describe its purpose or capabilities
GDPR permissions	The default GDPR settings are: Hide GPS position Driver identification is hidden Access to historical data is limited to the data retention period defined in the data privacy rules of the organization Select or clear the following checkboxes as required to comply with GDPR: Hide GPS position Hide driver identification Select the Access limited to historical data for checkbox and specify the number of days for which historical data is to be provided. NOTE: The number of days cannot exceed the data retention period defined. In this example, data for the last 30 days will be shared with the partner organization If this checkbox is not selected, the historical data will be shared based on the data retention period defined by your organization.
Teams	Teams that can access the integrator You can specify whether everyone can access the integrator, or restrict access by specifying a team. To allow integrator access to all users, select the No team assigned option. To restrict access to a specific team, select the Specific team(s) only option. In the Enter a team list, enter the team name. The Assigned teams section is displayed with () indicating the number of users in each team who can access the integrator. NOTE: Enter at least three characters to start a search operation. To create a new team: In the Enter a team list, enter the team name, and then from the list, select Add as a new team. The Add team dialog is displayed with the team name filled in. Enter a description for the team, and then click Save. The new team is formed and added to the Assigned teams section. The specified teams can access the integrator. NOTE: You can specify multiple teams that can access the integrator. To unassign a team, click X next to the team name. An organization can create up to 250 teams. A user or an integrator can be assigned to a maximum of 25 teams. A resource: asset, place, or driver can follow the maximum limit as mentioned above. Teams for integrators: Assets can be leased to multiple clients, which introduces the potential risk of exposing sensitive information to unauthorized users while sharing data across these clients. The Teams for Integrators feature provides a granular level of data access, ensuring that integrators can only access information related to assets assigned to their respective teams. This approach maintains confidentiality and prevents inadvertent data breaches. By restricting integrators to accessing only data relevant to their assigned assets, this feature ensures data privacy and strengthens security. NOTE: If the Mark as Master integrator checkbox is selected in the Name section, the integrator will obtain access to all the resources, and the team-specific access assigned will be negated.
Permission type	Select the permission type: Full control or Customized control NOTE: You can assign permission at the integrator level (applies to all the available APIs) or at the individual module level. If the permission type selection is a combination of Read only and Full control, the permission type control is updated to Custom automatically. If you click Full control at the integrator level, the customer can access all the APIs available under all the modules. If you click Customized control, you can manage permission types at the module level as shown below. Module-specific permission In the above example, an organization can perform CRUD operations related to the Asset Management module. For module-level access, select one of the following permission types: Select all – Full control: Assigns full control to all the APIs across modules Select all – Read: Assigns read access to all the APIs across modules Select all – None: No permissions are assigned to access the APIs Custom: Enables custom access to each module based on selection. In the example below, the customer is assigned permission to access 106 APIs. They are assigned full control for Asset Management APIs, read permission for User Management APIs, and none for Team Management APIs

The integrator created is listed on the Integrators page. The client ID and secret can now be viewed for the added integrator, which can be shared with the respective partner or consumer.

Edit an integrator #

You can modify integrator details, such as name, description, GDPR permissions, module-wise API permission types, and select or clear the Mark as Master integrator checkbox.

In the Admin module > from the left navigation pane, click Integrators . The Integrators page is displayed.
Select the required integrator record from the list. The integrator details page is displayed.
Click the Edit link. The Edit page is displayed.
Modify details in the Name including Mark as Master integrator feature, Description, GDPR permissions, and Permission type sections, and then click Save. The integrator details are modified. For more information about each section, see how to add an integrator.

Remove an integrator #

Remove an integrator from the SCALAR platform permanently if it is not required anymore.

From the Admin module > click Integrators . The Integrators page is displayed.
Go to the Remove integrator section, and then click Remove. A dialog is displayed for confirmation.
Click Remove integrator. The integrator is removed permanently from the SCALAR platform.

View integrators #

You can view the list of integrators both organization-specific and marketplaces on the Integrators page.

NOTE:

If required, you can mark an integrator as a Master integrator, which will provide the integrator access to all the resources irrespective of their team affiliation.
Organization-specific integrators are defined, managed, and controlled by your organization and are listed on the Internal tab.
On the Marketplace tab, based on frequent use cases, a standard list of partners who provide value-added services is created and provided by the ZF Integration team through the Service Portal. You can edit the GDPR permission settings for any partner on this tab.

In the Admin module, from the left navigation pane, click Integrators . The Integrators page is displayed.

Available columns

Column name	Description
Name	Name of the integrator
Permission type	Permission type assigned: whether full or customized control
Mark as Master integrator	Indicates whether the integrator is marked as a master integrator
Client ID	Unique ID generated and shared with the client to access the APIs, like a user name
Secret	Code generated (like a password) and shared with the client, which is used to generate an authentication token to access the APIs
Teams	Teams that can access the integrator

NOTE:

To view the secret code, click the Show all secrets link.
To copy the client ID, or reveal or copy the secret code, hover over a record. The icons to copy and reveal the secret are displayed. Click the icon to copy or reveal as required.

The client ID and secret ID can also be copied from the Integrator details page.
To view the partner information, click the Marketplace tab. The Marketplace tab is displayed wherein you can view the partner link and know whether the partnership is activated.

Search an integrator #

You can search a specific integrator on the Integrators page.

In the Admin module, from the left navigation pane, click Integrators . The Integrators page is displayed.
To search a specific integrator, enter the name of the integrator in the Search box. The integrator record is displayed.

NOTE:

The search functionality is also available on the Marketplace tab.

Track changes to integrators in audit log #

You can track and trace the changes made to an integrator from the Audit log module.

NOTE:

CRUD operations performed are tracked for organization-specific integrators.
Activation and deactivation of partnerships and changes made to the GDPR permission settings are tracked for marketplace integrators.

In the Admin module, from the left navigation pane, click Audit log . The Audit log page is displayed.
Click Filters. The Filter pane is displayed.
From the Record type section, select Integrator. Logs having record type as Integrator are displayed.

Filter integrators #

On the Integrators page, you can filter integrator records to narrow search results. You can search for internal and marketplace integrators.

To open the Filters pane, on the Integrators page, click Filters. The Filters panel is displayed.

Select the required options in the Permission type, Teams, and Mark as Master integrator sections. The results matching the selection criteria are displayed.

To filter the marketplace integrators, click the Marketplace tab, and then select the required options in the Activated, Teams, and Mark as Master integrator sections. The results matching the selection criteria are displayed.

Select Region and Language

User Documentation

Hardware Installation Guides

Integrator management

What is an integrator? #

Purpose #

Benefits of using integrators #

Marketplace integrators #

Partnership engagement #