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.

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       

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.

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.

1. 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.

   
   
2. In the Name column, select an integrator link to view details of the partner and their service offerings. The integrator details page is displayed.
3. To enter into a partnership with a partner > click Activate. The Establish a new partnership dialog is displayed.
   
4. 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.

Modify GDPR Permissions #

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

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

   
   NOTE:
   

   By default, the permissions related to GDPR are selected.

   
   
   
    
4. 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.

Deactivate a Partnership #

You can discontinue a partnership engagement by deactivating the partnership.

1. On the Marketplace tab, select the integrator name link from the list. The integrator details page of the partner is displayed.
2. Click Deactivate. The Deactivate integrator dialog is displayed.
3. To confirm the action, click Deactivate.
   
   A confirmation message is displayed indicating deactivation of the integrator. An email notification is sent to you and the partner. The partnership is deactivated and the data sharing with the partner company is stopped.

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.

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.

1. In the Admin module, from the left navigation pane, click Integrators . The Integrators page is displayed.
   
   
2. Click Add integrator. The Add integrator page is displayed.
   
   
3. 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.
   Description	Provide information about the integrator to describe its purpose or capabilities
   GDPR permissions	The default GDPR settings are: – GPS position is hidden – 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 in the box, 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.
   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 this example, the customer is assigned permission to access 89 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, and module-wise API permission types.

1. In the Admin module > from the left navigation pane, click Integrators . The Integrators page is displayed.
2. Select the required integrator record from the list. The integrator details page is displayed.
3. Click the Edit link. The Edit page is displayed.
4. Modify details in the Name, Description, GDPR permissions, and Permission type sections, and then click Save. The integrator is modified in the SCALAR platform. 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.

1. From the Admin module > click Integrators . The Integrators page is displayed.
2. Go to the Remove integrator section, and then click Remove. A dialog is displayed for confirmation.
3. 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.

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
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

Search an Integrator #

You can search a specific integrator on the Integrators page.

1. In the Admin module, from the left navigation pane, click Integrators . The Integrators page is displayed.
2. 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.

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