Define the OAS based RESTful service endpoints

All calls to the RESTful service of a third-party component are defined in the same configuration object called Resource Bundle.

1. In Alfabet Expand, go to the Reusable Elements tab.
2. In the explorer, right-click the Resource Bundles node and select the Create New Bundle option.
3. Click the new Bundle child node of the Resource Bundles node.
4. Set the following attributes in the attribute window:
   • Assistant: Select GenericAPIIntegration_OASAssistant.
   • Bundle Type: Select OpenAPISpecification.
   • Name: Enter a name for the resource bundle. The name is used in the explorer and to identify the resource bundle in other parts of the generic API integration interface configuration.
   • Description: Optionally enter a description to explain the purpose of the configuration to other users.
   • Group: If you would like to group the configurations in folders beneath the Resource Bundles explorer node, enter a folder name to create a folder or to add the resource bundle to an existing folder with the specified name.
5. Right-click the resource bundle and select the Create using OAS Assistant. The resource bundle editor opens.
6. Define a name for the API connection definition in the OAS Connector Name field. This name is used to identify the configuration in later configuration steps.
7. Click the arrow on the right of the Import OAS File field and select the OAS compliant swagger definition file of the third-party component for import.
8. Repeat the following steps in the given order for each connection to a RESTful end point of the third-party component.

   In this configuration step, the endpoints for either data import to or data export from the third-party component are selected and parameters are defined, if applicable. In the swagger definition, the following information is relevant for this configuration step:

    

   1. If the swagger file definition contains tags to group endpoints, you can first select a tag in the Tag attribute to reduce the list of endpoints in the Path to REST API Endpoint attribute to endpoints with the selected tag.
   2. Select an endpoint in the Path to REST API Endpoint attribute.
   3. Select the method in the Operation attribute. Use GET for import of data to Alfabet and POST for import of data to the third-party component. You can view in the swagger file if the method is available for the selected endpoint.
   4. Click the Save OAS API Connector button.

   Parameters which need to or may be added to the RESTful service call are listed after selecting the path and the operation. This is for informational purposes only.

9. Go to the Map Response tab.

   In this tab, the mapping of data between Alfabet and the RESTful service call response third-party component is prepared. The actual operational execution of data import or export will be performed via ADIF. ADIF is using temporary tables as intermediate step to prepare Alfabet data for export or data coming in from the third-party component for import to Alfabet.

   The third-party RESTful service is returning the data in the format that is defined in the swagger editor in the section Response of each endpoint description.

    

   During data import the data will be added to a temporary table structure that can then be used in the ADIF definition to map import data to standard Alfabet object class database tables.

   For data export, the return value may include data that shall be re-imported to Alfabet. For example, if a new object is created in the third-party component for each Alfabet object of a defined object class and the return value includes the unique ID of the objects in the third-party component, the ID can be mapped to a custom property of the Alfabet object class to store the information which object in the third-party component corresponds to which object in Alfabet.

10. Provide a parameter mapping for all endpoints that you defined as an OAS API connector:
    1. Click the New button.
    2. Select the operation in the Operation field.
    3. Enter a name for the temporary table that will be created for the ADIF scheme to store the incoming data from the third-party component or the Alfabet data gathered for export to the third-party component.
    4. Set a checkmark in the column Include in the table listing all the body fields returned for the endpoint by the third-party component. If many fields are returned, you can use the Search options to search for fields and the Show All Includedbutton to return to all results.

       The table shows the fields with the correct data type extracted from the swagger specification.

       If a JSON field contains a JSON array, the data type for the field must be set to Text.

    5. Click Save Mapping to save the mapping.