Microapps

Integrate SAP Concur

Integrate with SAP Concur to submit requests and receive notifications about approvals, expenses, itineraries, and reports.

Note

We provide two SAP Concur integration templates for your use. We recommend using the newer template in the Integrations category for most use-cases as it provides more power to configure the cached data structure. Find the Legacy (Deprecated) integration template details at SAP Concur - Add the legacy integration.

For a comprehensive list of out-of-the-box SAP Concur microapps, see Use SAP Concur microapps.

Review prerequisites

These prerequisites assume you administer the SAP Concur instance of your organization to set up the integration. You must have these details to add the integration in Citrix Workspace Microapps:

  • Base URL: The Base URI (also known as the Instance URL) is the domain where the SAP Concur platform entity resides. We refer to this as the Base URL. For more information, see SAP Concur - Base URIs.
  • Token URL: https://us.api.concursolutions.com/oauth2/v0/token
  • Authorization URL: https://us.api.concursolutions.com/oauth2/v0/authorize
  • Username: This and Password are the credentials of the service account with access to SAP Concur.
  • Password: This and Username are the credentials of the service account with access to SAP Concur.
  • Client ID: You collect the Client ID by registering the OAuth client in your SAP Concur account. The Client ID and the Client Secret are the same for both Service authentication and Service action authentication. See Request Client ID and Client secret.
  • Clent secret: You collect the Client secret by registering the OAuth client in your SAP Concur account. The Client ID and the Client secret are the same for both Service authentication and Service action authentication. See Request Client ID and Client secret.
  • Scope: CCARD creditcardaccount.read receipts.read COMPD USER user_read EMERG JOBLOG company.read ERECPT ITINER FISVC LIST PASSV mileage.vehicle.writeonly CONFIG FOP mileage.rate.writeonly receipts.writeonly GHOST user.read CONREQ user.write COMPANY mileage.journey.read EVS TRVPTS ATTEND INVPO NOTIF TRVREQ SUPSVC company.write EXPRPT EXTRCT PAYBAT INVPMT mileage.vehicle.read IMAGE TAXINV RCTIMG UNUTX TWS TMCSP quickexpense.writeonly BANK INVVEN openid receipts.write travelrequest.write MTNG mileage.rate.read mileage.journey.writeonly INSGHT TRVPRF INVTV MEDIC TSAI

Note:

It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

  • You must have the Web Services component purchased from SAP Concur. If your company hasn’t purchased the Web Services component, ask the SAP Concur administrator in your organization to contact your Account Manager at SAP Concur.
  • Configure Citrix Gateway to support single sign-on for SAP Concur so that once users log in they are automatically logged in again without having to enter their credentials a second time. Follow the instructions in Concur Single Sign-on Configuration. For more information about configuring SSO, see Citrix Gateway Service.

Request Client ID and Client secret

Obtain a new oauth2 client_id and client_secret and define the scope of client’s application following these instructions.

Important:

Create a support ticket with Concur to configure the integration using OAuth 2.0 and register correct authentication callback URLs. We recommend using the following text for your support ticket:

We request OAuth 2.0 credentials to enable an integration with Citrix Workspace. This tool downloads recent expense reports and line item details using a service account to present pending approvals to managers. It allows employees to submit, approve, and reject expenses. Actions taken by end users are directed to the 3LO authorization page where they enter their Concur credentials and approve access by the Workspace app.

Add the following authorized redirect URLs to Concur for this integration with authorization grant access granted to allow access to private data and enable OAuth authenticated user actions. The first callback that is listed does not change. The second callback depends on the target application, and can be found in your URL address bar when creating the integration. The section {yourmicroappserverurl} is composed of a tenant part, a region part, and an environment part: https://{tenantID}.{region(us/eu/ap-s)}.iws.cloud.com:

  • <https://microapps_server_URL/admin/api/external-services/com.sapho.services.concur.ConcurService/auth/serverContext>

  • <https://microapps_server_URL/app/api/auth/serviceAction/callback>

Add the integration to Citrix Workspace Microapps

Add the SAP Concur HTTP integration to Citrix Workspace Microapps to connect to your application. This delivers out-of-the-box microapps with pre-configured notifications and actions which are ready to use within your Workspace. The authentication options are preselected. Ensure that these options are selected as you complete the process. We recommend using this newer HTTP integration for most use-cases. The HTTP integration provides more power to configure the cached data structure.

Follow these steps:

  1. From the Microapp Integrations page, select Add New Integration, and Add a new integration from Citrix-provided templates.
  2. Choose the SAP Concur tile.
  3. Enter an Integration name for the integration.
  4. Enter Connector parameters.
    • Enter the instance Base URL.
    • Select an Icon for the integration from the Icon Library, or leave this as the default Salesforce icon.
    • Enable the On-premises instance toggle if you are creating an on-premises connection. For more information, see On-premises instance.
  5. Under Service authentication, select OAuth 2.0 from the Authentication method menu and complete the authentication details. Use the OAuth 2.0 security protocol to generate request/authorization tokens for delegated access. It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

    1. Select OAuth 2.0 from the Authentication method menu.
    2. Select Resource Owner Password from the Grant type flow menu. Provide the correct credentials to authorize resource server provision of an access token.
    3. Enter password in the Grant type value menu.
    4. Select Request body from the Token authorization menu.
    5. Select URL encoded form from the Token content type menu.
    6. The Token URL is prefilled: https://us.api.concursolutions.com/oauth2/v0/token
    7. Leave the Refresh token URL and Scope fields empty.
    8. Enter your Username and Password.
    9. Enter your Client ID and Clent secret.
    10. Leave Header prefix empty.
  6. Under Service Action Authentication, enable the Use Separate User Authentication in Actions toggle. Service action authentication authenticates at the service action level.

    1. Select OAuth 2.0 from the Authentication method menu and complete the authentication details.
    2. Select Authorization code from the Grant type flow menu. This grants a temporary code that the client exchanges for an access token. The code is obtained from the authorization server where you can see the information the client is requesting. Only this grant type enables secure user impersonation. This will display the Callback URL, which you use when registering your application.
    3. Enter authorization_code in the Grant type value menu.
    4. The Callback URL field is prefilled.
    5. Select Request body from the Token authorization menu.
    6. Select URL encoded form from the Token content type menu.
    7. The Authorization URL is prefilled: https://us.api.concursolutions.com/oauth2/v0/authorize
    8. The Token URL is prefilled: https://us.api.concursolutions.com/oauth2/v0/token
    9. Leave the Refresh token URL field empty.
    10. The Scope field contains the following scopes: CCARD creditcardaccount.read receipts.read COMPD USER user_read EMERG JOBLOG company.read ERECPT ITINER FISVC LIST PASSV mileage.vehicle.writeonly CONFIG FOP mileage.rate.writeonly receipts.writeonly GHOST user.read CONREQ user.write COMPANY mileage.journey.read EVS TRVPTS ATTEND INVPO NOTIF TRVREQ SUPSVC company.write EXPRPT EXTRCT PAYBAT INVPMT mileage.vehicle.read IMAGE TAXINV RCTIMG UNUTX TWS TMCSP quickexpense.writeonly BANK INVVEN openid receipts.write travelrequest.write MTNG mileage.rate.read mileage.journey.writeonly INSGHT TRVPRF INVTV MEDIC TSAI
    11. Enter your Client ID and Clent secret.
    12. Leave Header prefix empty.
  7. (Optional) If you want to activate rate limiting for this integration, enable the Request rate limiting toggle and set the Number of requests per Time interval.
  8. Request timeout is set to 120 by default.
  9. (Optional) Enable Logging toggle to keep 24 hours of logging for support purposes.
  10. Select Save.

You are now ready to set and run your first data synchronization. For complete information about synchronization rules, synchronization that does not meet its schedule and veto rules, see Synchronize data.

Use SAP Concur microapps

Our SAP Concur integration comes with the following preconfigured out-of-the-box microapps:

Approvals: Approve pending expense reports or send them back.

Notification or Page Use-case workflows
Approval Reminder notification When an expense report is pending approval and passes a defined threshold before deadline (for example, 3 days by default), the approver receives a notification reminder.
New Request notification When a new request for approval is assigned to an approver, the approver receives a notification.
New Request notification When there is a change to a request for approval, the approver receives a notification.
Expense Detail page Provides a read only view of an expense with details.
Expense Report Detail page Provides a detailed view of a report with a list of expenses with options to Approve and Send Back.
My Pending Approvals page Provides a personalized list of pending approvals.

Expenses: Search and view expenses.

Notification or Page Use-case workflows
My Expense Detail page Provides a detailed view of an expense with attachments.
My Expense Report Detail page Provides a detailed view of a report with a list of expenses with the option to Recall.
My Expenses page Provides a searchable, personalized list of expenses.

Itineraries: Search, view, and share itineraries.

Notification or Page Use-case workflows
Changed Itinerary successfully booked notification When a user’s itinerary is changed, the user receives a notification.
Changed Shared Itinerary notification When a changed itinerary is shared with a user, they receive a notification.
New Itinerary successfully booked notification When a user’s new itinerary is booked and ticketed, the user receives a notification.
New Shared Itinerary notification When an itinerary is shared with a user, they receive a notification.
Itinerary Detail page Provides a view of a user’s itinerary and an actionable share button.
My Itineraries page Provides a personalized list of itineraries.

Reports: Search and view your submitted expense reports.

Notification or Page Use-case workflows
Request Approved notification When a user’s expense report is approved, they receive a notification.
Request Send Back notification When a user’s expense report is sent back, they receive a notification.
My Expense Detail page Provides a detailed view of an expense with attachments.
My Expense Report Detail page Provides a detailed view of a report with a list of expenses with the option to Recall.
My Expense Reports page Provides a list of expense reports.

Add the legacy integration

As a System Admin, you use the following process to enable the Concur Integration. Ensure you meet the prerequisites then set up the Concur integration. After you set up the integration, you must provide employees with the employee name, email address, employee id, or log-in id of the dedicated account and ask them to adjust their SAP Concur profile settings. After you complete this process, your existing level of audit logging persists, including any actions carried out by the use of Citrix Microapps.

Review prerequisites

These prerequisites assume you administer the SAP Concur instance of your organization to set up the integration. You must have these details to add the integration in Citrix Workspace Microapps:

  • Instance URL
  • Username
  • Password

For OAuth 2.0:

  • OAuth Client ID
  • OAuth Client Secret
  • Authorization URL

Note:

It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

  • Obtain a new oauth2 client_id and client_secret and define the scope of client’s application.

Important:

Create a support ticket with Concur to configure the integration using OAuth 2.0 and register correct authentication callback URLs. We recommend using the following text for your support ticket:

We request OAuth 2.0 credentials to enable an integration with Citrix Workspace. This tool downloads recent expense reports and line item details using a service account to present pending approvals to managers. It allows employees to submit, approve, and reject quick expenses. Actions taken by end users are directed to the 3LO authorization page where they enter their Concur credentials and approve access by the Workspace app.

Add the following authorized redirect URLs to Concur for this integration with authorization grant access granted to allow access to private data and enable OAuth authenticated user actions. The first callback that is listed does not change. The second callback depends on the target application, and can be found in your URL address bar when creating the integration. The section {yourmicroappserverurl} is composed of a tenant part, a region part, and an environment part: https://{tenantID}.{region(us/eu/ap-s)}.iws.cloud.com:

  • <https://microapps_server_URL/admin/api/external-services/com.sapho.services.concur.ConcurService/auth/serverContext>

  • <https://microapps_server_URL/app/api/auth/serviceAction/callback>

  • You must have the Web Services component purchased from SAP Concur. If your company hasn’t purchased the Web Services component, ask the SAP Concur administrator in your organization to contact your Account Manager at SAP Concur.
  • Configure Citrix Gateway to support single sign-on for SAP Concur so that once users log in they are automatically logged in again without having to enter their credentials a second time. Follow the instructions in Concur Single Sign-on Configuration. For more information about configuring SSO, see Citrix Gateway Service.

Configure the legacy template

Add the SAP Concur integration to Citrix Workspace Microapps to connect to your application. This delivers out-of-the-box microapps with pre-configured notifications and actions which are ready to use within your Workspace.

Follow these steps:

  1. From the overview page, select Get Started.

    The Manage Integrations page opens.

  2. Select Add New Integration, and Add a new integration from Citrix-provided templates.
  3. Choose the SAP Concur tile.
  4. Enter a name for the integration.

    Concur connector parameters, Instance, URL, Authentication Method, Username, Password, Consumer Key

  5. Enter the Connector parameters that you collected as prerequisites.
    • Enter your Instance URL.
    • Enter the Username and Password.
    • Select an Authentication Method. Use the OAuth 2.0 security protocol to generate request/authorization tokens for delegated access.
    • Enter an Authorization URL to define the authorization server url provided when setting up the target application integration.
    • Select an OAuth 2.0 Authentication Method.
      • Credentials The client’s credentials are used instead of the resource owner’s. The access token is associated either with the client itself, or delegated authorization from a resource owner.
      • Authorization grant (3LO) The resource owner allows access.
    • Enter the OAuth Client ID and OAuth Client Secret that you collected in the prerequisites procedure.
  6. Select the following radio buttons as required:

    • Expense module Provides access to employee expense tracking.
    • Expense Group Configuration Retrieves the list of Expense Polices, Expense Types, and Payment Types for the Expense Group that the OAuth access token is assigned to.
    • Expense Report Details (allocations and Itemizations) Allows for the retrieval of allocation information as it relates to a Report ID, Entry ID, or Itemization ID.
    • Travel module Provides access to travel data such as itineraries, travel profiles, and travel requests.
    • Expense delegators Retrieves a list of users that have granted delegate permissions to the user specified in the OAuth access token.
  7. Enter a quantity for Number of Connections. This value determines the number of strings the data sync initiates.

    Note:

    The default number of connections is one. Opening more connections reduces the time for data synchronization, but increases the load on the Microapps server and can influence its performance. If you require, we recommend no more than 10.

  8. Select Add.

The Microapp Integrations page opens with your added integration and its microapps. From here you can add another integration, continue setting up your out-of-the-box microapps, or create a new microapp for this integration.

You are now ready to set and run your first data synchronization. As a large quantity of data can be pulled from your integrated application to the Microapps platform, we recommend you use the Table page to filter entities for your first data synchronization to speed up synchronization. For more information, see Verify needed entities. For complete information about synchronization rules, synchronization that does not meet its schedule and veto rules, see Synchronize data.

For more details of API endpoints and table entities, see Concur connector specifications.

Use SAP Concur legacy microapps

Existing application integrations come with out-of-the-box microapps. Start with these microapps and customize them for your needs.

Important!

These SAP Concur microapps are now deprecated: Submit Quick Expense, Create User, and User. Users need to delete these microapps as they will become misconfigured. To delete the microapp, from the Microapps Integrations page select the menu next to the microapp that you want to delete. Select Delete microapp and confirm.

How to delete a microapp

Our SAP Concur integration comes with the following preconfigured out-of-the-box microapps:

Approvals: Approve pending expense reports or send them back.

Notification or Page Use-case workflows
Approval Reminder notification When an expense report is pending approval and passes a defined threshold before deadline (for example, 3 days by default), the approver receives a notification reminder.
New Request notification When a new request for approval is assigned to an approver, the approver receives a notification.
New Request (changed) notification When there is a change to a request for approval, the approver receives a notification.
Expense Detail page Provides a read only view of an expense with details.
My Pending Approvals page Provides a personalized list of pending approvals.
Review Report page Provides an actionable form with a detailed view of an expense report pending approval.

Expenses: Search and view expenses.

Notification or Page Use-case workflows
Expense Detail page Provides a read only view of an expense with details.
My Expenses page Provides a personalized list of expenses.
Report Detail page Provides a detailed view of an expense report with a field for commenting.

Itineraries: Search, view, and share itineraries.

Notification or Page Use-case workflows
New Itinerary successfully booked notification When a user’s new itinerary is booked and ticketed, the user receives a notification.
New Shared Itinerary notification When an itinerary is shared with a user, they receive a notification.
Itinerary Detail page Provides a view of a user’s itinerary and an actionable share button.
My Itineraries page Provides a personalized list of itineraries.
Share Itinerary page Provides a form for sharing a user’s itinerary.

Reports: Search and view your submitted expense reports.

Notification or Page Use-case workflows
Request Approved notification When a user’s expense report is approved, they receive a notification.
Request SendBack notification When a user’s expense report is sent back, they receive a notification.
Expense Detail page Provides a read only view of an expense with details.
Expense Report page Provides a detailed view of an expense report with a field for commenting.
My Pending Expense Reports page Provides a personalized list of expense reports.
Integrate SAP Concur