Audit Search API

PUBLIC2022-05

Audit Search APISAP Ariba APIsSAP Ariba Developer PortalSAP Ariba BuyingSAP Ariba Buying and InvoicingSAP Ariba Invoice ManagementSAP Ariba Strategic Sourcing Suite

© 2

022

SAP

SE o

r an

SAP affi

liate

com

pany

. All r

ight

s re

serv

ed.

THE BEST RUN

Content

Audit Search API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

About Audit Search API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Workflow for the Audit Search API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5How to retrieve audit data asynchronously using the Audit Search API. . . . . . . . . . . . . . . . . . . . . . . . . . .5How to retrieve audit data synchronously using the Audit Search API. . . . . . . . . . . . . . . . . . . . . . . . . . . 8Error messages returned by the Audit Search API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Version history for the Audit Search API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

API-specific disclaimers and legal information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2 PUBLICAudit Search API

Content

Audit Search API

This guide is for a developer seeking to use the Audit Search API to retrieve stored audit data.

Developers can create a client application on the SAP Ariba developer portal to retrieve the audit data from the audit service synchronously or asynchronously, filter the data, and download it.

This guide applies to:

● SAP Ariba APIs● SAP Ariba developer portal● SAP Ariba Buying and Invoicing● SAP Ariba Buying● SAP Ariba Invoice Management● SAP Ariba Strategic Sourcing Suite

Audit Search APIAudit Search API PUBLIC 3

About Audit Search API

As part of audit compliance requirements, SAP Ariba solutions and Ariba Network must store information about changes made. Configuration changes, master data changes, and changes related to transactions need to be recorded for audit purposes. Customers can use the audit service provided by SAP Ariba to store this audit data.

The Audit Search API enables customers to consume the stored audit data. This REST API can be used to retrieve the audit data asynchronously or synchronously from the audit service. Asynchronous search is useful when audit data for long periods need to be retrieved. Synchronous search helps retrieve audit data for the most recent 3-month period. The data will be batched and can be downloaded as ZIP files, containing either CSV or JSON files, to be used for reporting or other audit-related needs.

This API includes the following endpoints:

POST /jobs This endpoint is used to submit an audit search job for querying audit data matching the filter criteria. This is used for asynchronous retrieval of audit data.

GET /jobs/{jobId}

This endpoint is used to query the status of the submitted job. This is used for asynchronous retrieval of audit data.

GET /jobs/{jobId}/files/{fileId}

This endpoint is used to download the search results as a ZIP file. This is used for asynchronous retrieval of audit data.

GET /jobs This endpoint retrieves a list of all existing audit search jobs and can be filtered using jobId, auditType, serviceName, and status. This is used for asynchronous retrieval of audit data.

GET /audits This endpoint is used to fetch audit records synchronously. This is used for synchronous retrieval of audit data.

Restrictions

This API is currently available only in the US and EU data centers. It is expected to be available in other data centers in a future release.



Workflow for the Audit Search API

The workflow for the Audit Search API includes the following high-level steps.

Workflow for asynchronous audit search

1. The SAP Ariba solution logs audit data in the audit service.2. The client application posts a reporting job to the job queue, specifying the audit type and the filter criteria

specified in the OData format. It receives a job ID in response.3. The client application polls the job status using the job ID in the API until the job is complete.4. When the job is complete, the output is ready for download.5. The client application requests the output document, specifying the job ID and the file ID.6. The downloaded ZIP file contains the output as a CSV or JSON file, depending on what was specified in the

reporting job.7. Optional. The client application requests a list of all submitted reporting jobs for a site, specifying the desired

filter.

Workflow for synchronous audit search

1. The SAP Ariba solution logs audit data in the audit service.2. The client application sends a request for audit data, specifying the tenant ID, audit type, start and end date of

the search range, and the filter criteria specified in the OData format.3. The API call returns the list of audit log entries matching the query parameters in the JSON response.

How to retrieve audit data asynchronously using the Audit Search API

Prerequisites

● To create an application and request access to use this API, you must have access to the SAP Ariba developer portal. For details refer to “Steps to start using the APIs” in the help for The SAP Ariba developer portal.

● All queries made to this API must be authenticated using OAuth authentication. For details refer to “Developer Portal Authentication” in the help for The SAP Ariba developer portal.

Audit Search APIAbout Audit Search API PUBLIC 5

Context

The following steps describe the process to retrieve audit data asynchronously using the Audit Search API for SAP Ariba solutions.

NoteIn the sample URLs in this topic, replace {{runtime_url}} with the desired runtime URL from the Environment Details table on the SAP Ariba developer portal discovery page for this API.

Procedure

1. The client application posts the initial request to the jobs queue, using the POST /jobs endpoint, specifying the audit type and the criteria for filtering the audit data in the request body.

POST {{runtime_url}}/jobs { "tenantId":"p2pTeSap-2", "Body":"searchStartTime ge '2019-01-22T08:02:10.000+0530' and searchEndTime le '2019-07-22T09:00:00.000+0530' and auditType in ('Security', 'DataAccess') and documentId eq 'invoice002100'"}

tenantId The unique ID of the solution for which to get the audit data. Specify the realm ID of the site to get audit data for SAP Ariba solutions. Specify the Ariba Network ID to get audit data for Ariba Network.

Body The OData filter to identify the audit data to download. The filter consists of the following query options:○ auditType: A comma separated list of audit types to be used to search for data. This is

mandatory.○ searchStartTime: The start date from which audit records needs to be present in the

report, in the yyyy-MM-dd'T'HH:mm:ssZ format. This is mandatory.○ searchEndTime: The end date till which audit records needs to be present in the report, in

the yyyy-MM-dd'T'HH:mm:ssZ format.○ queryCriteria: The query criteria to be given in OData format on the audit data fields. The

query supports all fields except createdTime, auditType, and serviceName. Use the /schemas endpoint to get the list of supported fields. The following fields are listed along with possible values:○ Action:

○ For Security audit type: LOGIN, LOGOUT, AUTHENTICATION, and ADMINISTRATION

○ For DataAccess audit type: READ○ For DataModification audit type: INSERT, UPDATE, and DELETE

For GenericAction audit type: DOWNLOAD, LISTING



○ For ConfigurationModification audit type: ENABLE and DISABLE○ For Integration audit type: DATAIMPORT and DATAEXPORT

○ PurposeOfAudit: PCI, PII, BusinessCritical, and SecurityEvent○ Status: SUCCESS, FAIL, and TIMEOUT

○ orderby: A comma separated list of audit data fields based on which the results will be ordered.

○ serviceName: A comma separated list of service names whose audit data is to be filtered. These service names correspond to one of the SAP Ariba solutions or Ariba Network.

○ reportFormat: The output format in which the audit data is downloaded. The supported formats are CSV and JSON. The default format is JSON. If no value is specified for this parameter, the output will be in the default JSON format.

○ recordsPerFile: The number of records to be included in each report file. The default value is 10000 records, which is also the maximum limit.

○ jobName: The name specified for the audit search request job.○ jobDescription: The description of the audit search request job.○ createdUser: The name of the user that created the audit search request job.○ jobCreatedTime: The time when the audit search request job was created.○ customLabels: A comma separated list of audit data fields and their corresponding custom

labels to be displayed in the audit report.

The response contains a job ID corresponding to the asynchronous audit search job initiated with the specified criteria.

2. The client application queries the status of the reporting job using the GET /jobs/{jobId} endpoint. This request returns the job status.

GET {{runtime_url}}/jobs/{jobId}

$jobId The job ID returned from the POST /jobs query.

The response contains the status of the asynchronous audit search job matching the specified job ID. The job status can be one of the following:○ pending○ inprogress○ completed○ failed

3. The client application downloads the audit data document identified by the asynchronous audit search job, using the GET /jobs/{jobId}/files/{fileId} endpoint. The size of the downloaded file can be up to 10 MB.

GET {{runtime_url}}/jobs/{jobId}/files/{fileId}

$jobId The job ID returned from the POST /jobs query.

$fileId The file ID of the output file generated after the job is completed.

This request downloads the report file as a ZIP file with the file name in the following format: {fileId}.zip.


4. Optional. The client application requests a list of all the reporting jobs by site using the GET /jobs endpoint.

GET {{runtime_url}}/jobs?tenantId={tenantId}&$filter={filter}&orderBy={field}&$skip={skip}&$top={top}

tenantId The unique ID of the site for which to get the audit data.

$filter The OData filter criteria to identify the jobs to list. The filter consists of the following query options:○ jobId: The job ID of the reporting job. This lists only the job corresponding to the specified

job ID.○ auditType: The type of audit for which the reporting job was requested. This lists all jobs

requested for the specified audit type.○ serviceName: The name of the service on which the reporting jobs to be listed are run.○ status: The status of the reporting job. This lists all the jobs with the specified status. The

status can be one of the following:○ pending○ inprogress○ completed○ failed

○ jobName: The name specified for the audit search request job.○ jobDescription: The description of the audit search request job.○ createdUser: The name of the user that created the audit search request job.○ jobCreatedTime: The time when the audit search request job was created.

$orderby A comma separated list of audit data fields based on which the results will be ordered. Only the following fields can be specified: jobId, auditType,serviceName, and status.

$skip The number of jobs to be skipped from the beginning of the search results.

$top The number of jobs to be returned in the response.

How to retrieve audit data synchronously using the Audit Search APIPrerequisites

● To create an application and request access to use this API, you must have access to the SAP Ariba developer portal. For details refer to “Steps to start using the APIs” in the help for The SAP Ariba developer portal.

● All queries made to this API must be authenticated using OAuth authentication. For details refer to “Developer Portal Authentication” in the help for The SAP Ariba developer portal.



Context

The following steps describe the process to retrieve audit data synchronously using the Audit Search API.

NoteIn the sample URLs in this topic, replace {{runtime_url}} with the desired runtime URL from the Environment Details table on the SAP Ariba developer portal discovery page for this API.

Procedure

The client application requests a list of audit records that match the criteria, using the GET /audits endpoint.

GET {{runtime_url}}/audits?tenantId={tenantId}&auditType={auditType}&searchStartTime={date}&searchEndTime={date}&$filter={filter}&$orderby={field}&$skip={skip}&$top={top}

tenantId The unique ID of the solution for which to get the audit data. Specify the realm ID of the site to get audit data for SAP Ariba solutions. Specify the Ariba Network ID to get audit data for Ariba Network.

auditType A comma-separated list of audit types for which audit data is to be retrieved. This is mandatory.

searchStartTime The start date from which audit records needs to be present in the report, in the yyyy-MM-dd'T'HH:mm:ssZ format.

searchEndTime The end date till which audit records needs to be present in the report, in the yyyy-MM-dd'T'HH:mm:ssZ format. If this value is not specified, the API uses the current date and time.

$filter The OData query criteria on the audit data fields used to identify the audit records to retrieve. The query supports all fields except createdTime and auditType. Use the /schemas endpoint to get the list of supported fields. The following fields are listed along with possible values:○ Action:

○ For Security audit type: LOGIN, LOGOUT, AUTHENTICATION, and ADMINISTRATION

○ For DataAccess audit type: READ○ For DataModification audit type: INSERT, UPDATE, and DELETE

For GenericAction audit type: DOWNLOAD, LISTING○ For ConfigurationModification audit type: ENABLE and DISABLE○ For Integration audit type: DATAIMPORT and DATAEXPORT

○ PurposeOfAudit: PCI, PII, BusinessCritical, and SecurityEvent○ Status: SUCCESS, FAIL, and TIMEOUT

$orderby A comma separated list of audit data fields based on which the results will be ordered.

$skip The number of audit records to be skipped from the beginning of the search results.


$top The number of audit records to be returned in the response. The maximum value is 5000.

$count Specifies whether the total count of audit records must be added to the response. The value can be true or false.

This request contains a list of audit records matching the specified query criteria in the response.

Error messages returned by the Audit Search APIUse this information to troubleshoot your queries to the Audit Search API.

Error messages returned by the POST /jobs query

Error code Message Description

400 The API key passed in the request is not valid.

The API key passed in the query headers does not match the API key in the OAuth token.

400 Invalid body format. {{Dynamic error response}}.

One of the body parameters has an invalid format. The second part of the message dynamically indicates the parameter with the invalid format. For example, if this part of the error message is: Invalid date format for searchStartTime; the expected format is [yyyy-MM-dd'T'HH:mm:ssZ]., it indicates that the date format for searchStartTime is an invalid, along with the expected format.

401 Unauthorized Authentication failed. The token has expired or is invalid. A new token needs to be generated.

500 Internal Server Error This indicates a system error such as memory or network issues. Contact your system administrator.



Error messages returned by the GET /jobs/{jobId} query




400 InvalidJobId The specified job ID is not valid. Check to make sure you are using using a valid job ID.


Error messages returned by the GET /jobs/{jobId}/files/{fileId} query




400 InvalidJobId The specified job ID is not valid. Check to make sure you are using using a valid job ID.


Error messages returned by the GET /jobs?tenantId={tenantId}&$filter={filter}&$orderby={field}&$skip={skip}&$top={top} query




400 OData filter contains invalid fields. {{Dynamic error response}}.

One of the fields in the OData query is not valid. The second part of the message dynamically indicates the invalid field.




500 Internal Server Error This indicates a system error such as memory or network issues. Contact your system administrator.

Error messages returned by the GET /audits?tenantId={tenantId}&auditType={auditType}&searchStartTime={date}&searchEndTime={date}&$filter={filter}&$orderby={field}&$skip={skip}&$top={top} query




400 Invalid query format. {{Dynamic error response}}.

One of the query parameters has an invalid format. The second part of the message dynamically indicates the parameter with the invalid format. For example, if this part of the error message is: Invalid date format for searchStartTime; the expected format is [yyyy-MM-dd'T'HH:mm:ssZ]., it indicates that the date format for searchStartTime is an invalid, along with the expected format.




Version history for the Audit Search API

Please use the active version of the Audit Search API.

API version Status As of release

1 Active N/A

Related Information

https://help.sap.com/viewer/b61dd8c7e22c4fe489f191f66b4c48d6/cloud/en-US/792a3139e5c04f0cbbcbbd404506bc04.html

Audit Search APIVersion history for the Audit Search API PUBLIC 13



API-specific disclaimers and legal information

The SAP Ariba developer portal included in the SAP Ariba APIs product and the APIs made available on this site are provided solely at the discretion of SAP without warranty of any kind, and SAP may change, suspend, or cancel any or all features or functions of the SAP Ariba APIs product or revise the web site at any time. Any production use of or commercialization of applications containing any APIs provided on this web site is prohibited without a written agreement between your company and SAP governing such activities.

Access to this API is available to you as a subscriber to this solution as part of the SAP Cloud Service Level Agreement. However, it is not considered part of the solution. Use of this API is purely optional and is subject to restrictions stated in the documentation, including the Terms of Use and the documentation found at the SAP Ariba developer portal (see https://developer.ariba.com/api ). If you wish to connect a third-party service using this API, first confirm that the company is participating in the SAP partner program and is authorized to provide connection to this solution using this API. You will be required to submit written consent to SAP to authorize the exchange of data with the third-party service.


API-specific disclaimers and legal information

http://help.sap.com/disclaimer?site=https%3A%2F%2Fdeveloper.ariba.com%2Fapi

Important Disclaimers and Legal Information

HyperlinksSome links are classified by an icon and/or a mouseover text. These links provide additional information.About the icons:

● Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your agreements with SAP) to this:

● The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.● SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any

damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.

● Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering a SAP-hosted Web site. By using such links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this information.

Videos Hosted on External PlatformsSome videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within the control or responsibility of SAP.

Beta and Other Experimental FeaturesExperimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use the experimental features in a live operating environment or with data that has not been sufficiently backed up.The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.

Example CodeAny software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of example code unless damages have been caused by SAP's gross negligence or willful misconduct.

Bias-Free LanguageSAP supports a culture of diversity and inclusion. Whenever possible, we use unbiased language in our documentation to refer to people of all cultures, ethnicities, genders, and abilities.

Audit Search APIImportant Disclaimers and Legal Information PUBLIC 15

www.ariba.com

© 2022 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice.

Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary.

These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies.

Please see https://www.sap.com/about/legal/trademark.html for additional trademark information and notices.

THE BEST RUN

http://www.ariba.com

https://www.sap.com/about/legal/trademark.html

Audit Search API

Documents

Transcript of Audit Search API