Function

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

Usage considerations

Authorizing users & getting data

• 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

• 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

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

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
    )
  )
)

Integrations writing data

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
              )
            )
          }
        )
      }
    )
  )
)

Feature compatibility