🚧

Use with caution

The Advanced configuration of the SAP Signavio integration is only required for certain edge cases and shouldn't normally be required.

This guide is focused on advanced SAP Signavio use cases and technical information.

Endpoints

SAP Signavio provides endpoints to obtain SAP Signavio Processes as well as Glossary Items as structured data.

The LeanIX SAP Signavio Integration currently provides access to three SAP Signavio endpoints. The path within the structured data can be specified in the Information Source field of the configuration with a starting keyword that refers to each endpoint.

In the following sections we will describe how to explore the data that can be obtained from those endpoints using the Chrome Browser.

Editordata Endpoint

In this section we are going to explain how to use the Developer Tools of the Chrome Browser to explore the data retrievable from the /p/editordata?id=(id) endpoint.

Process Language Example

In the basic configuration examples available in the user documentation, we wanted to write the language of a process into a custom Fact Sheet field. The image below shows the language attribute within the JSON retrieved from the editordata endpoint using the Developer Tools. The path to the language has to start with the editordata keyword, because we obtain the data from this endpoint. Then the path within the data structure has to be added which is model.properties.language. Finally we have the complete path editordata.model.properties.language that can be added into the Information Source field.

Model Endpoint

In this section, we are going to explain how to use the Developer Tools of the Chrome Browser to explore the data retrievable from the /p/model/(id)/info endpoint. The SAP Signavio model editor does not call the endpoint itself, that's why we are going to use the /p/directory/ endpoint to retrieve the same data as given by the /p/mode/(id)/info endpoint.

Glossary Endpoint

In this section we are going to explain how to use the the Developer Tools of the Chrome Browser to explore the data retrievable from the /p/glossary/(id)/info endpoint. The /p/glossary/(id)/info endpoint itself is not used by the browser when loading a glossary item but it is still possible to explore the data via the /p/glossary endpoint that is used to get the data.

Advanced Tab

SAP Signavio Integrations allows additional options to control the synchronization at a higher level of detail. Next to the Basic section in the settings page we also have the Advanced section, which shows the complete configuration as a data structure and allows us to modify it using a provided JSON editor.

The difference in using the Basic section compared to the Advance section is that we can introduce more complex expressions in certain properties. To avoid edition of these complex expressions using the Basic section, they are shown as disabled input fields.

In the following sections, we will explore the structure of the configuration data and show how to modify it for more complex synchronization scenarios. These sample configurations cases cover the Basic cases introduced before followed by JSON configurations. Afterward, we will introduce more complex mappings like Tags and Subscriptions.

To get a complete description of the JSON data structure of the configuration, see the section The Configuration Data Shape.

Case 1: A SAP Signavio Field to a Static Value

The synchronization that assigns a fixed value to a Fact Sheet field as shown in the Basic Section (Basic Case 1):

The equivalent configuration in JSON format is shown in the following listing:

{
 "inboundMappings": [
  {
   "leanixType": "factSheetField",
   "fields": [
    {
     "leanixFieldName": "comment",
     "inboundPropertyPath": "Synchronized by LeanIX Signavio Integration",
     "valueMappings": []
    }
   ]
  }
 ]
}

Case 2: SAP Signavio Attributes to Fields

The configuration that synchronizes a SAP Signavio attribute into a Fact Sheet Field is shown (Basic Case 2):

The corresponding JSON structure is:

{
 "inboundMappings": [
  {
   "leanixType": "factSheetField",
   "fields": [
    {
     "leanixFieldName": "language",
     "inboundPropertyPath": "${editordata.model.properties.language}",
     "valueMappings": []
    }
   ]
  }
 ]
}

New Fact Sheets created will have the field language with the same value taken from the SAP Signavio endopoint editordata, the value for the path given in inboundPropertyPath is explained in Endpoints. The expression ${...} is part of EL (Expression Language) used by Leanix SAP Signavio Integration to offer a flexible way to work with data from SAP Signavio Endpoints.

📘

For the properties with names in the format, meta-xxx use the inboundPropertyPath as below.

"inboundPropertyPath": "${editordata.model.properties use the inb}"

Case 3: SAP Signavio attributes with Value Mappings

In this case the SAP Signavio attribute language in mapped into a custom Fact Sheet field language. Additionally, the value is mapped from their common name into the international two-letter code (Basic Case 3):

The JSON data structure shows the list of value mappings as maps inside the valueMappings keyword.

{
 "inboundMappings": [
  {
   "leanixType": "factSheetField",
   "fields": [
    {
     "leanixFieldName": "language",
     "inboundPropertyPath": "${editordata.model.properties.language}",
     "valueMappings": [
      {
       "outputExpression": "EN",
       "regexMatch": "English"
      },
      {
       "outputExpression": "DE",
       "regexMatch": "German"
      }
     ]
    }
   ]
  }
 ]
}

The regexMatch keyword allows to define a Regular Expression. In this example it is a fixed string and the value retrieved from the inboundPropertyPath editordata.model.properties.language will be compared to this string. The first matching mapping will be used and the outputexpression will be written into the leanix field specified in leanixFieldName.

It is easily possible to define a default avlue that is used if none of the defined (regEx) options match.
This functionality is only available in the JSON (advanced) configuration. In the below example all other languages or empty input will result in "Other"

{
 "inboundMappings": [
  {
   "leanixType": "factSheetField",
   "fields": [
    {
     "leanixFieldName": "language",
     "inboundPropertyPath": "${editordata.model.properties.language}",
     "valueMappings": [
      {
       "outputExpression": "EN",
       "regexMatch": "English"
      },
      {
       "outputExpression": "DE",
       "regexMatch": "German"
      }
     ],
     "defaultValue": "Other"
    }
   ]
  }
 ]
}

Case 4: Multiple SAP Signavio Attributes Combined

In this case we will combine two SAP Signavio attributes into Fact Sheet field. In our example we are going to write into a custom Fact Sheet field called publish. We need to identify the path to the attributes we want to combine, in our case: model.status.publish and model.type. Some values we could find in SAP Signavio for model.type attribute are: Organization Chart, Event-driven process chain (EPC), or Business Process Diagram (BPMN 2.0), and for model.status.publish are true, false. As a result we expect to have a value like true - Business Process Diagram (BPMN 2.0).

{
 "inboundMappings": [
  {
   "leanixType": "factSheetField",
   "fields": [
    {
     "leanixFieldName": "publish",
     "inboundPropertyPath": "${model.status.publish} - ${model.type}",
     "valueMappings": []
    }
   ]
  }
 ]
}

The keyword inboundPropertyPath defines the path to obtain the data from SAP Signavio endpoints, however it is not restricted to only express data paths, it is also possible to use all functionality provided by EL (Expression Language: https://jcp.org/en/jsr/detail?id=245

.) expressions. As in our example, we can concatenate two SAP Signavio attributes separated by dash - character.

After the synchronization, the publish Fact Sheet field will have the value reslfrom the concatenation of model.status.publish attribute, then a dash character(- ) followed by the value of model.type. The next image shows the History view where we can find the value for field publish set to false - Organization Chart.

Case 5: Use Complex Expressions in Value Mappings

Inside valueMappings keyword, each element of the list allows the mapping of the value to a final result given by the keyword outputExpression. In previous examples, we set fixed text values in this keyword, however it is possible to use more complex EL expressions that combine other objects of data.

In the following JSON config, we are combining part (the first 5 characters) of the SAP Signavio name concatenated with the attribute language to obtain the final value for the field processnumber.

{
 "inboundMappings": [
  {
   "leanixType": "factSheetField",
   "fields": [
    {
     "leanixFieldName": "processnumber",
     "inboundPropertyPath": "${model.name}",
     "valueMappings": [
      {
       "outputExpression": "${input.substring(0,5)} - ${editordata.model.properties.language}",
       "regexMatch": "^[0-9].*"
      }
     ]
    }
   ]
  }
 ]
}

In outputExpression, the symbol input represents the result obtained after the expression in inboundPropertyPath (the model name: ${model.name}) is resolved. In general, the input keyword is only available in outputExpression and offers a flexible way to modify the inboundPropertyPath value. We are also verifying that only models that have a name that starts with a number are used to obtain the processnumber field, this is guaranteed by the regexMatch "^[0-9].*" .

After the synchronization, an SAP Signavio Diagram named 1.1.3 Summary of objections is synchronized to a Fact Sheet with the value 1.1.3 - English in the field processnumber.

📘

Unknown property handling

It might be that some advanced expressions may contain references to properties on SAP Signavio Processes that exist for some processes but do not exist on others. To avoid error messages, a flag "ignoreUnknownProperty" can be set to true. By using this, the admin can keep the logs clean in cases where such warnings are expected and can be ignored.

{
 "inboundMappings": [
  {
   "leanixType": "factSheetField",
   "fields": [
    {
     "leanixFieldName": "processnumber",
     "inboundPropertyPath": "${model.name}",
     "valueMappings": [
      {
       "outputExpression": "${input.substring(0,5)} - ${editordata.model.properties.language}",
       "regexMatch": "^[0-9].*"
      }
     ],
     "ignoreUnknownProperty": true
    }
   ]
  }
 ]
}

Case 6: Tagging Fact Sheets using SAP Signavio Attributes

In this sample case, we want to map the value of publish attribute in SAP Signavio to be applied as a tag in LeanIX. To synchronize SAP Signavio attributes into Fact Sheet tags, we have to define the fields that compose a Tag: name and group, also set the leanixType to tag. The following JSON configuration data shows an example of synchronization to tags.

{
 "inboundMappings": [
  {
   "leanixType": "tag",
   "fields": [
    {
     "leanixFieldName": "group",
     "inboundPropertyPath": "PublishStatus",
     "valueMappings": []
    },
    {
     "leanixFieldName": "name",
     "inboundPropertyPath": "${model.status.publish}",
     "valueMappings": [
      {
       "outputExpression": "published",
       "regexMatch": "true"
      },
      {
       "outputExpression": "non-published",
       "regexMatch": "false"
      }
     ],
     "defaultValue": "",
     "ignoreUnknownProperty": true
    }
   ]
  }
 ]
}

New Fact Sheets will be tagged as published or non-published depending of the value from SAP Signavio publish attribute. The tag group for all Fact Sheets will be PublishStatus. It is necessary that the Tag Group and Tags are created by the Administrator before the synchronization, the bellow image shows the tag groups for this example:

Both fields group and name are resolved using the same mechanism explained in previous sections, which consists in taking the value from inboundPropertyPath and use it together with valueMappings list to calculate the final result. In our example the group is resolved as a static text: PublishStatus, and the name of the tag is based on the value mapping of the model.status.publish value.

After the synchronization, the Fact Sheet created has the tag non-published because the SAP Signavio attribute model.publish was false.

📘

Tagging Mode Multiple/Single

In order to remove the existing tags when a new tag is supposed to be applied recommendation is to use mode "Single"

Case 7: SAP Signavio Collaboration Hub

To be able to go to the SAP Signavio Collaboration Hub directly from the LeanIX interface we need to add a new custom field to the specified process fact sheet and configure a inboundmapping. The custom field has to be called collaborationHubUrl. And the inboundmapping configuration is shown below:

{
 "inboundMappings": [
  {
   "leanixType": "factSheetField",
   "fields": [
    {
     "leanixFieldName": "collaborationHubUrl",
     "inboundPropertyPath": "${model.status.publish}",
     "valueMappings": [
      {
       "outputExpression": "https://editor.signavio.com/p/hub-preview#model/${editordata.modelId}",
       "regexMatch": "true"
      },
      {
       "outputExpression": "",
       "regexMatch": "false"
      }
     ]
    }
   ]
  }
 ]
}

In our example the link to the SAP Signavio Collaboration Hub is only shown when the model is published. The two possible values for model.status.publish are true or false, using the valueMappings we are filtering the cases for true to have the URL that points to SAP Signavio Collaboration Hub. To build a URL for each model we need to add the id from editordata.modelId. The domain as well as the path in the URL might be different for your SAP Signavio setup.

After the synchronization, all published models will be shown with a Collaboration Hub link in the LeanIX interface:

Case 8: Mapping SAP Signavio Attributes to Subscriptions

In this sample case, we will show how to synchronize SAP Signavio Attributes to add Subscriptions in LeanIX Fact Sheets. Business Owner defined in SAP Signavio models will have a subscription to the corresponding Fact Sheet as role Process Owner with the type Responsible.

We set leanixType keyword as subscription, and add the field definitions for a Fact Sheet Subscription: email , type, role, and optionally comment, as shown in the JSON configuration:

{
 "inboundMappings": [
  {
   "leanixType": "subscription",
   "fields": [
    {
     "leanixFieldName": "email",
     "inboundPropertyPath": "${glossaryItem.get(editordata.model.properties['meta-processowner']).metaDataValues['meta-zustndigeemailadresse']}",
     "valueMappings": []
    },
    {
     "leanixFieldName": "type",
     "inboundPropertyPath": "RESPONSIBLE",
     "valueMappings": []
    },
    {
     "leanixFieldName": "comment",
     "inboundPropertyPath": "Subscription role added by Signavio integration",
     "valueMappings": []
    },
    {
     "leanixFieldName": "role",
     "inboundPropertyPath": "Process Owner",
     "valueMappings": []
    }
   ]
  }
 ]
}

• leanixFieldName = email Field: Defines the data path to obtain the email address from SAP Signavio. This is a two steps process: first, obtain the data for the SAP Signavio Item that represents a Role for business Owner; and second, obtain the Glossary Item data associated with the previous reference. In the inboundPropertyPath expression , the data path editordata.model.properties['meta-processowner'] resolves to a value similar to "/glossary/<id>", which is then used by the symbol glossaryItem.get(...) to obtain a complete Glossary Item data object; then, the email is taken from the Glossary Item using the path .metaDataValues['meta-zustndigeemailadresse'].
• leanixFieldName = type Field: Defines the value for the type of subscription.
• leanixFieldName = role Field: Defines the value for the role of the subscription, in our example Process Owner.
• leanixFieldName = comment Field: Defines the comment applied to the subscription.

It is necessary the LeanIX administrador creates the Subscription Roles before the synchronization is executed, for this example the role to create is: Process Owner. Also, for every email that is obtained during the synchronization, it is expected that a LeanIX user email already exists, otherwise the subscription will be ignored for that non-existing email address and a warning will be logged to Sync Logging.

Case 9: Mapping SAP Signavio Glossary Items to Fact Sheets

In this case, we will create Fact Sheets based on SAP Signavio Glossary Items making use of advanced inbound mapping capabilities. The Glossary Item in SAP Signavio Dictionary is shown bellow.

In the bellow data configuration we can see the glossaryCategorySyncDescriptors property of the global configuration that contains one element defining the options for the synchronization. We suppressed some parts of the config for clarity and shows only the inboundMappings section.

{
 "glossaryCategorySyncDescriptors": [
  {
   "inboundMappings": [
    {
     "leanixType": "factSheetField",
     "fields": [
      {
       "leanixFieldName": "meta_cause",
       "inboundPropertyPath": "${glossary.metaDataValues['meta-cause']}",
       "valueMappings": [
        {
         "outputExpression": "${input.replaceAll('^[0-9.]+ (.*)','$1')}",
         "regexMatch": "^[0-9.]+ .*"
        }
       ]
      },
      {
       "leanixFieldName": "meta_consequence",
       "inboundPropertyPath": "${glossary.metaDataValues['meta-consequence']}",
       "valueMappings": [
        {
         "outputExpression": "${input.toUpperCase()}",
         "regexMatch": "^possible.*"
        }
       ]
      }
     ]
    }
   ]
  }
 ]
}

In the previous data configuration, there are two elements that define mapping options for two Fact Sheets fields:

• In leanixFieldName = meta_cause Field: It takes the value from SAP Signavio attribute meta-cause obtained using the mechanism explained in Signavio Endpoints section. Using valueMappings we are only considering those values that have numbers in its content. The last expression inside outputExpression defines how to modify the data before applying to the Fact Sheet, for our example we are removing the numeric part from 0.1.2 Admission of candidates.

• In leanixFieldName = meta_consequence Field: It takes the value from SAP Signavio attribute meta-consequence. In valueMappings we are only considering those values that starts with the word possible. The last expression inside outputExpression defines how to modify the data, which for our example is converting the value to uppercase.

The new Fact Sheet created using the previous configuration is shown bellow. The values for the fields meta_cause and meta_consequence are Admission of candidates and POSSIBLE OUTRAGE respectively.

Case 10: Ignoring linked Process Model relations based on Custom Attributes for Top-Down and Bottom-Up

SAP Signavio offers linkage of diagrams (eg: process models) against each other based on a special custom attributes type Diagram Link. Some customers uses this way of linkage to express a special relationship between objects. Such a custom attribute can be defined in Setup / Define notation/attributes, like:

In case a Process Model should be linked via a custom attribute, the linkage must be done inside the Custom Attributes area at the right side of the screen. For instance this looks like:

To exclude relations based on custom attributes for the top-down or bottom-up synchronizations, the field excludeCustomRelations must be set to true.

{
 "processSyncDescriptors": [
  {
   "inboundMappings": [],
   "active": true,
   "directoryIds": [
    "10d342f5db704199968d86688c528073"
   ],
   "linkProcessingMode": "PARENT_CHILD",
   "publishedOnly": false,
   "startNodeId": null,
   "filterExpression": null,
   "leanixParentFactSheetId": null,
   "blacklist": [],
   "shortDescription": "",
   "excludeCustomRelations": true
  }
 ]
}

Case 11: maximumDeletionRatio used to protect of unwanted data loss

The configuration field maximumDeletionRatio specifies a ratio that is always checked before the synchronization decides whether or not to delete data in strict mode in LeanIX or SAP Signavio. This feature is a kind of safety net used to protect your data when setting up or changing the synchronization configuration and this is not perfect and contains mistakes.

Before a deletion the synchronization computes for each process sync descriptor and glossary sync descriptor the ratio:
computed ratio = 100 * / <Number of items processed (read)>

A deletion of items is only allowed in case of :
a) < 10 OR
b) < maximumDeletionRatio

{
 "active": true,
 "maximumDeletionRatio": 50,
 "timerBasedSync": true
}

Case 12: forceWrite used to create glossary items with conflicting name

For glossary item synchronizations that go from LeanIX to SAP Signavio, the configuration field forceWrite can be used to create or update glossary items that already exist on the SAP Signavio side in different glossary categories. In Signavio, it is possible to create entries with the same name in different categories. However, a confirmation step is required to proceed with the creation of the entry, maintaining the normal behavior of preventing duplicate glossary items.

{
 "glossaryCategorySyncDescriptors": [
  {
   "active": true,
   "forceWrite": true
  }
 ]
}

🚧

forceWrite should be only used after careful analysis of the SAP Signavio workspace

forceWrite should be only used after careful analysis of the SAP Signavio workspace as this will create duplicates in SAP Signavio GlossaryCategory.

Case 13: Include tasks in relations to Glossaries

You can configure the Signavio-Integration to list all tasks used in a process which are connected to a glossary, in the synchronized relation in LeanIX.
The tasks will be shown as an alphabetically sorted list of task-names in the configured field of the synced relation.

In this example below, three tasks are all connected to the glossary item "Contract Management" and both the glossary item and process are synchronized to LeanIX:

When configured correctly this is how the tasks will be synchronized and shown in LeanIX:

To enable this behaviour, add a field leanixTasksRelationField to specify the relation's field that represents the SAP Signavio tasks. In the example below, the relation field lxSignavioTasks will store the SAP Signavio tasks names between Process and Application:

{
  "processFactSheetType": "Process",
  "glossaryCategorySyncDescriptors": [
    {
      "factSheetType": "Application",
      "relationName": "relProcessToApplication",
      "leanixTasksRelationField": "lxSignavioTasks",
      ...
    }
  ],
  ...
}

Because Process and Application are used for the signavio synchronization in the example, the relation relProcessToApplication must contain the field lxSignavioTasks.

To create this field, go to the Process Fact Sheet configuration page, select the "Applications" relation and add a new field:

You can also add a human-readable label for this Field or a help text:

For more information regarding the configuration of your Datamodel, see Create or remove relations

Case 14: Match Glossary Items Based on displayName

You can match the glossary item titles with Leanix Fact Sheet display names. This can be achieved with the following code snippet in the advanced configuration of integration.

{
 "glossaryCategorySyncDescriptors": [
  {
   "active": true,
   "nameResolvedByFSField”: “displayName"
  }
 ]
}

Configuration Complete JSON Example

A complete sample configuration structure is shown below. It is a JSON map where top level keywords represents global options that are applied to every synchronization. The sample list has been obfuscated to hide sensitive information, it is intended to be used only as a reference , not to be copied into your configuration.

{
 "active": true,
 "timerBasedSync": false,
 "strict": false,
 "processFactSheetType": "Process",
 "leanixConfig": {
  "workspaceId": "XXXXXX-5391-40c7-a47e-YYYYYY",
  "targetSystem": "https://url.for.server",
  "userId": "xxxxxxx-336a-4092-ae60-yyyy"
 },
 "signavioConfig": {
  "url": "https://editor.signavio.com",
  "username": "[email protected]",
  "password": "xxxxxxxxxx-xxxxxxxxxx",
  "tenantId": "f6a3ca755bec1e13xxfeb",
  "loginParams": ""
 },
 "glossaryCategorySyncDescriptors": [
  {
   "active": true,
   "factSheetType": "Application",
   "masterSite": "LEANIX",
   "strict": false,
   "relationName": "relProcessToApplication",
   "inboundMappings": [],
   "filter": null,
   "glossaryCategoryId": "d693d09****f87e290"
  }
 ],
 "processSyncDescriptors": [
  {
   "inboundMappings": [],
   "active": false,
   "directoryIds": [
    "1111111111111111"
   ],
   "linkProcessingMode": "NO_PROCESSING",
   "publishedOnly": false,
   "startNodeId": null,
   "leanixParentFactSheetId": null,
   "blacklist": [],
   "shortDescription": ""
  }
 ]
}

The corresponding Basic section for the previous Advanced data configuration is shown in the following image.

We can identify some elements between both sections, like the strict property, set to False as it is unchecked in the Basic section, similarly, the property processFactSheetType represents the Fact Sheet Type field set as Process, and the rows we have in sections SAP Signavio Processes and Glossary Category Mappings are kept in processSyncDescriptors and glossaryCategorySyncDescriptors properties in the structure.

Because almost all elements in the configuration are easily managed by using the Basic section, we will explain in detail the inboundMappings property where we will find elements that can be extended only using the Advanced section.

Advanced Filter to the Processes coming from SAP Signavio

When you want to only pull specific processes from SAP Signavio, you can filter in the advanced Section by using "filterExpression" attribute with JUEL expression.

"filterExpression": "${model.description.equals('SOME_VALUE')}"

📘

Links to glossary items used in filtered processes

The Integration will collect all linked glossary items that are used by filtered processes (like Applications) and link them to the last unfiltered process in the hierarchy. This allows to filter low level processes while still keeping all linked Glossary items and properly create relations from it.

Advanced Inbound Mappings (Processes and Glossary Items)

The inboundMappings can be used in both Processes and Glossary Items configurations, it consists of a list of JSON maps as shown.

{
 "inboundMappings": [
  {
   "leanixType": "",
   "fields": [
    {
     "leanixFieldName": "",
     "inboundPropertyPath": "",
     "valueMappings": [
      {
       "outputExpression": "",
       "regexMatch": ""
      }
     ]
    }
   ]
  }
 ]
}

Each element inside this list of Inbound Mappings have the following keywords:

• leanixType: Specify into which Leanix data type the data is written. Allowed values are:

• fields: A list that describes the incoming data path, how it is transformed and where it is written to.

Each member in fields list has the following properties:

• leanixFieldName: the Fact Sheet field where data is written into. Depending of the leanixType value, it should contain optional or required Fact Sheets fields. The table bellow shows the expected definitions for each possible value of leanixType:

For Processes:

For Glossary Items:

• inboundPropertyPath: Specify path/expression for SAP Signavio endpoints (See section SAP Signavio Endpoints). The symbols that are available are the same as shown in the table below:
  for outputExpression except for ${input}.
• valueMappings: Optional, it allows to specify mappings of the values that have been obtained based on inboundPropertyPath value.

Each member inside valueMappings have the following properties:

• regexMatch: A regular expression to which the value of the inboundPropertyPath has to match, the simplest case is an static text, but any Java Regular Expression could be used here. The elements in the list of value Mappings are evaluated until the first matched is found.

• outputExpression: An expression that resolves the final value for the Fact Sheet field. We can use fixed values, like a text, or the combination of multiple fields. The table bellow shows the symbols that are available inside the expressions.

For processes:

For Glossary Items:

The example expressions in the previous table follow the syntax defined by Expression Language (or just EL). EL expressions allows advanced operations like splitting, concatenating or selection of substrings for any of the symbols available. A description for EL can be found in https://jcp.org/en/jsr/detail?id=245.