Authorization Link

Function

Copy link to clipboard

a!authorizationLink( label, connectedSystem, showWhen )

Defines a link to authorize a user for a connected system that uses OAuth 2.0 Authorization Code grant. Links can be used in charts, grids, hierarchy browsers, images, link fields, milestones, pickers, and rich text.

See also:

• OAuth 2.0: Authorization Code Grant
• Link,
• Read-Only Grid,
• Images,
• Buttons and link design guidance

Parameters

Copy link to clipboard

Usage considerations

Copy link to clipboard

Authorizing users & getting data

Copy link to clipboard

• Be sure to read through the external system's documentation to understand what is returned when the user needs to authorize or reauthorize
• For integrations getting data, use dot notation. For integrations writing data use fv!connectedSystem.
• If the mobile user is signed in as one user in the mobile browser and a different user in the mobile app, authorization will fail.

Opening authorization links

Copy link to clipboard

• A link created by a!authorizationLink() opens in a new browser window.
• For mobile, a link created by a!authorizationLink() will open the device's default browser
  • Authorization links are made for mobile, so you don't need to worry about the user not being signed-in in the mobile browser.

Examples

Copy link to clipboard

Click EXPRESSION to copy and paste an example into the Interface Definition to see it displayed.

When connecting with OAuth, integrations can either get data from or post data to another system

Integrations retrieving data

Copy link to clipboard

Assuming that the integration used a custom error message that returned Access_token when an access token was missing, the following interface expression will provide an authorization link.

1
2
3
4
5
6
7
8
9
10
11
12
a!localVariables(
  local!integrationResult: rule!EXAMPLE_OAuthIntegration(),
  a!linkField(
    label: "Example Authorization Link",
    /* show when */
    showWhen: local!integrationResult.error.message = "Access_token",
    links: a!authorizationLink(
      label: "Authorize",
      connectedSystem: local!integrationResult.connectedSystem
    )
  )
)
Copy

Integrations writing data

Copy link to clipboard

If the integration is writing data to another system via OAuth, the integration would be called as a result of a save. These types of integrations, by default, return onSuccess and onError. fv!connectedSystem is returned when there's an error and can be retrieved through the onError parameter and used to populate the authorization link field.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
a!localVariables(
  local!results,
  local!connectedSystem,
  local!verify,
  a!sectionLayout(
    contents: a!columnsLayout(
      columns: {
        a!columnLayout(
          contents: {
            a!buttonLayout(
              secondaryButtons: {
                a!buttonWidget(
                  label: "Save Changes",
                  saveInto: {
                    a!save( local!verify, true),
                    rule!EXAMPLE_OAuthIntegration(
                      onSuccess: a!save( local!results, fv!result),
                      onError: a!save( local!connectedSystem, fv!connectedSystem)
                    )
                  }
                )
              }
            ),
            a!linkField(
              label: "Authorization After Write Attempt",
              showWhen: and(not(isnull(local!connectedSystem)), not(isnull(local!verify))),
              links: a!authorizationLink(
                label: "Authorize",
                connectedSystem: local!connectedSystem
              )
            )
          }
        )
      }
    )
  )
)
Copy

Feature compatibility

Copy link to clipboard

Feedback

Copy link to clipboard