UI Extensibility

Pagehooks are the first feature part of a new set of features under a category called UI Extensibility.

Pagehooks give customers the ability to place configurable buttons or navigation items in specific locations that can launch new browser tabs or windows to sites hosted outside of Aprimo. On task pages pagehooks can optionally be configured to display on specific steps in a workflow.

Aprimo can also provide context to the external application by dynamically populating pagehook tokens in the external URL.  Pagehook tokens fall into two categories:

• Contextual pagehook tokens, such as the record ID and page ID, allowing external sites to understand where the user was coming from in the application and what record they are viewing.
• The authorization code pagehook token, which lets you include an authorization code for the external website to retrieve a REST API access token. This can allow external sites to understand which user clicked the pagehook and make REST API calls on behalf of that user.

For example, if you place a button pagehook on the activity view page, provide an external URL of https://my.aprimoexternalapp.com/?ActivityID={{ID}}, and a user clicks on the button on record ID 2201, the resulting URL the user is taken to will be https://my.aprimoexternalapp.com?ActivityID=2201. This allows you to build external sites which may extend the Aprimo user interface, load record-specific externally created reports, and more.

If you wish to configure a pagehook with no contextual tokens, you can jump ahead to the section below Adding a pagehook button.

To add a pagehook with contextual token you will need to…

1. Configure the URL of your external application, along with any pagehook tokens you’d like to use, in a new integration registration under System Tools > Integration > Registrations.
2. Configure the Navigation Item or Button in Aprimo. When using pagehook tokens, the URL configured on the navigation item or button will need to follow the following format, where [registration_id] is replaced by the integer ID of the integration registration from step one, without the brackets. Following is the URL format and an example:

Format: LaunchExternalApp.aspx?aprimo_registration_id=[registration_id]
Example: LaunchExternalApp.aspx?aprimo_registration_id=83

When a navigation item or configurable button with this URL is clicked, the user’s browser will launch a new tab or window. When leveraging pagehook tokens, the user will be briefly redirected to the LaunchExternalApp.aspx page, the callback URL from the integration registration will be retrieved, any dynamic URL tokens are populated, and the user is redirected to the resulting URL.

You may skip this step if your URL does not use any pagehook tokens.

An integration client registration record is needed to interface with the Aprimo REST API or when using an external URL with pagehook tokens. This record includes the Redirect URL, which is the URL of your external target page, along with pagehook tokens. An Aprimo system administrator can add a registration by following these steps:

1. Navigate to System Tools > Integration > Registrations and click New
2. Enter the following required information:
   1. Client name
   2. Description
   3. Client Secret
   4. Redirect URL – your external URL with the pagehook tokens included (additional information on which pagehook tokens are available is below).

If your external application would like to get a REST API access token, note that you will need the Client ID and Client Secret values to retrieve one via the API. If your external site does not need to call back into the API, you will not need your client ID or secret value.

Button pagehooks are available on these pages:

• Activity Details view (page ID 2200)
  • Up to 5 buttons
• Activity Attachment view
  • Up to 5 buttons
• Activity Proposal Details View
  • Up to 5 buttons
• Commitment (page ID 2123 and 2000)
  • Up to 5 buttons
  • Displays on both the Commitment Details View and Activity Commitment Details View pages
• Project Details view (page ID 12093)
  • Up to 5 buttons
• Program Proposal Details View
  • Up to 5 buttons
• Program Details View
  • Up to 5 buttons
• System Tools
  • Up to 10 links in the bottom left of the page
  • Displays under “Other Links” navigation item
• Task Inbox
  • Up to 6 buttons/links
    • For the case of 2 pagehooks, they will display as buttons. If there are more than 2 then the second button becomes a drop-down list with title “ACTIONS” and can contain up to 5 links
  • Optional “Configure by Task” display mode with feature flag enabled
• Invoices (page ID 2153 and 2134)
  • Up to 5 buttons
  • Displays on both the Invoice View and Activity Invoice View pages

To create a pagehook navigate to the pagehook administration page:

System Administration > System Tools > Navigation Settings > Pagehooks

Click New and enter information into the fields:

1. Button display text (limited to 20 characters)
2. Button hover text
3. Select the page where the button should display (from the pages listed above)
   1. Note that only page view mode is supported. New and Edit mode are not supported
4. If a task page is selected, the display mode field will display. You may select “Always Display” or “Configure by Task”. See below for workflow step configuration.
5. Select button/link sequence
   1. Button configuration must respect limits listed above
6. Brief description of the button
7. URL where the button will link to
   1. If you are using pagehook tokens in your URL, provide the registration ID for your Integration Registration.
   2. If you are not using pagehook tokens, provide the direct link to external application – e.g. https://my.aprimoexternalapp.com/?Action=MassImportAssets
8. Status

Pagehook buttons will appear to the left of the existing buttons.

If you have a task page pagehook set to “Configure by Task”, you will be able to configure it to display on select tasks. To do this open your workflow designer and then open the step where you would like for the pagehook to display. At the bottom of the step details tab you will find a pagehooks section. You can add and remove pagehooks set to configure by task. Note that the number of pagehooks allowed to display on each page is still enforced.

Note: This feature leverages navigation items and groups. For specific information on how to set up navigation items and navigation groups please refer to Aprimo Help. Additionally, navigation items and the Aprimo homepage will be receiving a UX overhaul in the coming months! Stay tuned for more information on how that may affect pagehooks.

Navigation item pagehooks are placed in the user’s application navigation. Navigation item pagehooks only have the {{authorization_code}} token available to them. Because these reside on the main application navigation,there are no additional contextual tokens available to navigation items.

To leverage navigation item pagehooks, create your integration registration (instructions above), then configure a navigation item to point to LaunchExternalApp.aspx?aprimo_registration_id=83, where 83 is your integration registration ID. When a user clicks the navigation item, they will be briefly redirected to the LaunchExternalApp.aspx page, the URL from the integration registration will be retrieved, the {{authorization_code}} token will be populated, and the user will be redirected to the resulting URL.

URL Report pagehooks function the similar to navigation item pagehooks. When configuring a URL report, point it to https://yourtenant.aprimo.com/Aprimo/LaunchExternalApp.aspx?aprimo_registration_id=83 where 83 is your integration registration ID. When a user accesses the URL report, the iframe of the report will briefly be redirected to the LaunchExternalApp.aspx page, then directed onto your externally hosted application. Note that URL reports are iframed into the application, so your external application must support being framed in.

Button pagehooks may leverage additional contextual pagehook tokens to let your external app understand where a user has come from in Aprimo.

Aprimo does this by allowing you to use a page’s query string parameters as tokens in your callback URL.

For example, two of the query string parameters available on the Activity View page are ID, which represents the Aprimo Activity ID, and PageID, which represents the Aprimo page you are on. When configuring your integration registration, you may use these query string parameter names as pagehook tokens.

For example, let’s say you configured your callback URL as https://my.aprimoexternalapp.com/?Page={{PageID}}&ID={{ID}}, and configured a button pagehook on the activity view page to use this integration registration. A user who navigated to the Activity View page for activity ID 1001 and clicked your button pagehook would be sent to https://my.aprimoexternalapp.com/?Page=2200&ID=1001, where 2200 is the PageID for the Activity View page, and 1001 is the activity ID of the record the user was on.

Your callback url can use tokens as any part of the url, even URL segments. Following the above example, if you configured your callback url as https://my.aprimoexternalapp.com/Activities/{{ID}}, the user would be redirected to https://my.aprimoexternalapp.com/Activities/1001.

To identify the query string parameters that are available on a page, see the below section titled How to View Page Query String Parameters.

The {{authorization_code}} pagehook token can be used for the external application to get a REST API access token.

For example, say you configure your integration registration to have a callback URL as follows:

https://my.aprimoexternalapp.com/?Action=MassImportAssets&APIAuthCode={{authorization_code}}

When the pagehook is clicked, the user would briefly go to LaunchExternalApp.aspx, and then be redirected to:

https://my.aprimoexternalapp.com/?Action=MassImportAssets&APIAuthCode=ASDFR24SDFXZ

From there the external application can call back into the Aprimo REST API, get an access token, and then display Aprimo information accessible by the user. Please refer to the REST API documentation on Authorization for instructions on how to use an authorization code to retrieve an access token. You may follow the steps of the direct flow, starting at Step 3: Create a Base-64 Encoded Authorization Code.

• All Objects
  • ID
  • authorization_code
  • login_id
• Activity Details
  • PageID – The ID of the current page
• Activity Attachment
  • PageID – The ID of the current page
  • ObjectTypeID – The ObjectTypeID of the parent object
  • ObjectID – The ID of the parent object
  • ContextObjectID – Value of the Parent Object’s ID field (Same as ObjectID)
• Activity Proposal Details
  • Tab
  • PageID
• Commitments
  • Nothing unique
• Project Details
  • ActivityID – ID of the parent Activity
• Program Proposal Details
  • Nothing unique
• Program Details
  • Nothing unique
• System Tools
  • Nothing unique
• Task Inbox
  • ID – The query parameters don’t show this, but it exists
  • Status – ID of the current task’s status
  • taskName – Name of the current task
• Invoices
  • Nothing unique

You can see an example of what your page query string parameters are by double-clicking the bottom bar on the page where the button will reside.

A page will appear with the page context and will look something like this with page context in query string parameters. In the example below “&PageID=2200&ID=6901&Mode=2” will be appended to the configurable button URL when it is rendered on a page.