Skip to main content

Celonis Product Documentation

Connecting audit log, login history, and Studio adoption APIs to Celonis Platform

Within Admin & Settings you can view your audit log, team login history, and studio adoption statistics. However, these views are limited with standardized user interfaces. To run more in-depth analysis of this data, you can connect to their respective APIs and then use a data extractor to feed this information back into the Celonis Platform. This then lets you create your own views in Studio.

To connect to the APIs and create an extractor, follow these procedures in order:

Once the data is extracted, you can then create a data model using this data. You are then ready to go to Studio and create a view using the data from the API.

Creating an application and granting it API permissions

Tip

Alternatively, you can create an application key and assign the following permissions: Audit Log API, Login History API, and Studio Adoption APIs.

For more information, see: Application keys.

To start, you need to create an OAuth client in your team and then grant this client API permissions.

  1. Click Admin & Settings and select Applications.

  2. Click Add New Application - OAuth client and create your OAuth client.

    Create a new OAuth client. Click ​Add New Application​ -> ​OAuth client​​.

    When creating your OAuth client, use the following configurations:

    • Authentication method: Client secret post

    • Scopes to select:

      • audit.log:read (for the Audit Log API)

      • platform-adoption.tracking-events:read (for the Studio Adoption API)

      • team.login-history:read (for the Login History API)

      • team.user-group-info:read (for Team Members info API)

    New OAuth Client. Select the client scope: audit, platform-adoption, and team.

  3. Click Create and then copy the client ID and client secret to your clipboard for later use.

  4. Click Permissions and edit Team permissions.

    Edit_team_permissions.png

  5. Assign Audit Log API, Login History API, and Studio Adoption APIs permissions to your newly created application as required.

    assign_api_permissions.png

  6. Click Save.

    The OAuth client now has the relevant API permissions. You now need to request an OAuth access token.

Testing API with Swagger UI

You can now test your APIs with Swagger UI. To do this, you need your team name and environment cluster and your OAuth client from the earlier procedure.

You can find your team name and environment cluster from any URL, for example from the Permissions page from the procedure above.

https://[teamname].[realm].celonis.cloud/ui/team/permissions

With your team name and environment cluster, you can then access the Swagger UI using this URL:

https://[teamname].[realm].celonis.cloud/swagger-ui/index.html?configUrl=/log/v3/api-docs/swagger-config

Once on the Swagger UI, follow these steps to test your API:

  1. Click Authorize.

    The Swagger UI. You can test your API here.

  2. When using an OAuth client: Enter ‘Bearer’ followed by a space and then copy the client ID you obtained for the client. For example:

    Bearer XxxxxxAxxxxBxxxxCxxxXBBBBX

    When using an application key: Enter 'AppKey' followed by a space and then copy your application key from the earlier procedure. For example:

    AppKey XxxxxxAxxxxBxxxxCxxxXBBBB
    authorization_key.png

  3. Click Authorize. Once authorization is successful, click Close.

  4. Expand the GET call for the API you want to test and click Try it out.

    expand_and_try_it_out.png

  5. Click Execute.

    Click Execute to test your API with Swagger.

    You will now see the response from the API, including the header that shows the AppKey Token and the URL.

Creating an extractor for APIs

After testing your APIs, you now need to create an extractor. This extractor pulls detailed information from your team (via the API), allowing you to add this to your Studio views.

The extractor you create in the following steps is without both pagination and headers:

  1. From your team, click Data - Data Integration.

  2. Click New Data Pool - Create from scratch , add a name, and then click Save.

  3. From the data integration diagram, click Connect to Data Source and then select Connect to Data Source.

    connect_to_data_source.png

  4. Click Custom and then click the plus icon.

    Here you have three options:

    1. Build a new Extractor.

      create_custom_data_extractor.png

    2. Customize a Celonis extractor.

    3. Import from File (For Audit logs with pagination use this JSON template, this template can also act as the foundation for the Login Log API and the Adoption API).

    When building a new extractor using the four stage wizard, enter the following information:

    • Extractor name: This can be custom to your extractor.

    • Connection Parameters - Edit API URL: Enter your Celonis team URL in the following format - https://[Your Team].celonis.cloud

    • Authentication Methods:

      When using an OAuth client: Select OAuth2 (Client credentials). Enter https://[Your Team].celonis.cloud/oauth2/token for the Get Token Endpoint. Add an additional parameter with the key ‘scope’. The value should be the space-delimited scopes that you need (e.g. ‘audit.log:read team.login-history:read platform-adoption.tracking-events:read’’ for the Audit Log, Team Login History and Studio Adoption APIs).

      When using an application key: Select API Key Authentication and enter 'Authorization' in the API key header field.

    • Define Endpoints: Configure a new endpoint and enter an endpoint name.

    • Endpoint Configure Request: In URL enter {Connection.API_URL}/[Enter what is shown in the Swagger doc URL after celonis.com.cloud]

      So the final text could read: 

      {Connection.API_URL}/log/api/external/audit?Request parameters and Headers can be completed after as needed).{Connection.API_URL}/log/api/external/audit?

    • Endpoint Pagination Method: Select No Pagination (this will default to 200 rows).

      Note

      To configure pagination for all data (200 rows and above):

      • Select Page-by-Page pagination.

      • Enter "pageNumber" in the page parameter field.

      • Ensure "0" is shown in the First Page Index field.

      • Select “totalCount” in the optional Total Size Field in Response dropdown menu. This may only be visible after you have built the response, so come back after if this is the case.

    • Configure Response: Use the sample from your source system and add a new data source. When prompted for an API field key, enter the one used in step 2 of the Swagger test procedure. For example:

      AppKey XxxxxxAxxxxBxxxxCxxxXBBBB

    • Optional: Select “content” from the Response Root dropdown menu. This ensures you only push “Content” data into the data model and will remove columns such as pagesize, pagenumber, totalcount that may not be relevant.

  5. Click Save.

  6. Click Build Response.

  7. Click Finish.

Creating an extraction

Once your extractor is built, you can configure delta loads by following these steps:

  1. Click Add Extraction.

  2. Click on the Parameters tab.

  3. Click New Parameters and populate and save the parameters as follows:

    Placeholder: LastUpdated

    Name: Last Updated

    Type: Dynamic

    Table: AuthenticationEvents

    Column: timestamp

    Default value: 01/01/2000, 00:00:00

  4. Click on the Tab configuration tab and scroll to Delta Filter Statement and add the following:

    = from = <%=LastUpdated%>

  5. Now add a data model, a data model load and a schedule following the user interface.