Best Practices

Collection of suggested best practices and tips to optimize your usage of the Integration-API

Overview

Integration API offers a wide range of functionality. Expanding scope of Integration possibilities with LeanIX. For general use cases, please see Technical and API Guide. Here is a collection of some suggested best practices and tips to optimize usage of Integration API.

Admins have access to Integration API under the Developer section of the Administration section.

19111911

Integration API section comes preloaded with two examples.

Get Started Quickly

Use the UI

While we also have our REST API available, it is highly recommended to setup your processors in the UI before addressing the API.

16691669

Utilizing the UI allows for quick testing and debugging of processors.

Check Scope Before Firing Test Runs

Test runs on a large workspace can take up a lot of time and unnecessary processing. Setting a scope while doing testing ensures that the testing is quick and does not overload the system.

16691669 16691669

Adhere to Proper Processor Versioning Convention

Integration API Processors should always be versioned using the number.number.number format. (e.g. 1.0.0). Following this convention allows for maintaining versioning support in case there is an update to the processor.

16691669

Following the convention allows for version history of the processor to be saved and be accessible from the UI itself.

16691669

Operate Reliably

Utilize Webhooks

Our tutorial on Send Alerts to Slack and Teams can be used to set up alerts for Integration API runs that occur on a recurring basis.

One way to do this could be to have a separate slack channel wherein successful or unsuccessful runs are sent with a different emoji in their payload. :white-check-mark: , :warning: etc.

16361636
{
 "deliveryType": "PUSH",
 "id": "",
 "identifier": "Integration Statistics to Slack",
 "tagSets": [
  [
   "integrations",
   "statistics"
  ]
 ],
 "createdAt": "2020-06-10T15:17:11.064809Z",
 "workspaceId": "[Workspace ID from API Token section",
 "userId": "[User ID from API Token Section]",
 "targetUrl": "[SLACK TARGET URL]",
 "targetMethod": "POST",
 "authorizationHeader": "",
 "callback": "var payload = delivery.payload;delivery.active = false;var base_url = 'https://eu.leanix.net/WORKSPCENAME/';if((payload.progress == 'FINISHED') && (payload.connectorId == 'ConnectorID-3' || payload.connectorId == 'ConnectorID-1' || payload.connectorId == 'ConnectorID-2')){delivery.active = true;var text = ':SLACK EMOJI: '+'*Workspace:* WORKSPACE_NAME '+ '*Connector Id:* '+payload.connectorId+' *Scope:* '+ payload.scope+' *Connector Direction:* '+ payload.direction+' has *Status:* '+ payload.progress+' and *error count:* '+ payload.errorCount;text += ' *Synclog link :* '+base_url+'/admin/synclog/'+ payload.synchronizationId;}delivery.payload = {text : text}",
 "lastDeliveryStatus": 200,
 "ignoreError": false,
 "maxBatchSize": 512,
 "workspaceConstraint": "WORKSPACE",
 "active": true,
 "errorCount": 0,
 "firstTimeDeliveryFailed": null,
 "payloadMode": "DEFAULT"
}
16401640

Leverage Deletion Scope

Deletion scope can be used to set up automatic deletion when loading data using inbound Data Processors.

More details in our Advanced section

❗️

Examples provided can archive Fact Sheets

Executing examples in the section above needs to be done with care. All potentially existing project Fact Sheets in the workspace will be in scope for deletion. To limit, you may want to change the sample that a tag "TEST_PRJ" or similar will be set for the test projects. This tag can be added as filter criteria to the deletion scope definition.

Cover All Edge Cases to Eliminate Warnings and Errors

Whenever value mapping is defined in the processor, it is highly suggested to add a "catch-all" option at the end of the value mapping list. By doing so, warnings that arise from the processor on not finding any matching value from other value mapping list can be removed.

{
 "leanixType": "tag",
 "fields": [
  {
   "leanixFieldName": "group",
   "inboundPropertyPath": "Process Frequency",
   "valueMappings": []
  },
  {
   "leanixFieldName": "name",
   "inboundPropertyPath": "${editordata.model.properties[\"meta-processfrequency\"]}",
   "valueMappings": [
    {
     "outputExpression": "High",
     "regexMatch": "ci1560953961659160925663"
    },
    {
     "outputExpression": "Medium",
     "regexMatch": "ci1560953961659758129772"
    },
    {
     "outputExpression": "Low",
     "regexMatch": "ci1560953961659682886651"
    },
    {
     "outputExpression": "None",
     "regexMatch": "ci1560953961659123251220"
    },
    {
     "outputExpression": "Other value",
     "regexMatch": ".*"
    }
   ]
  }
 ]
}

In the example above, by using the last value mapping of "Other Value", the Integration will not output a warning in the sync log when it does not find any of the matching values defined.

Advanced

Leverage Workflows and Integration API to Create Metrics.

Workflows (in Administration > Workflows) can be used to automate and schedule the runs of Integration-API processors from the UI itself. One of the use-cases that we can derive out of this is to create metrics based out of fields within the workspace that are regularly updated.

📘

In case access to "Workflows" is required

You may reach out to support through our Support Form Submission or reach out to your CSM for more details
The section is available in every productive workspace per default.

"Workflows" are not associated with "Automations" in any kind.

LeanIX Store

Users are highly encouraged to share and consume premade configurations of Integration-API for a lot of common use-cases! This is mutually beneficial.

37323732

LeanIX Store can be accessed by admins from within the Workspace and Integration API configurations can be directly loaded to the workspace.