Office 365 update item permissions

Note: This is an external action and may execute on servers running outside your data center Centralized locations used to house servers used by Nintex for remote storage, processing, or distribution of data. Nintex has a number of regional data centers available for Nintex for Office 365. For information about Nintex data centers and where your data center is located, contact your Nintex account or territory manager. region. Before implementing, consider performance and regional concerns where digital boundaries are an issue. For more information, see In-tenant and external actions.

Use the Office 365 update item permissions action A tool for building the processes, logic, and direction within workflows. to update permissions of a specified item in a list or document library on a SharePoint site.

Permission must be provided by a tenant administrator, before workflow designers can start creating connections for this action using the connection type SharePoint Online: Update item permissions (OAuth2).

Note: Providing permission for a tenant has to be done only once, and after it is provided all workflow designers of the tenant can create connections for this action.

For more information about Connection types, see Connection types and Connector actions.

How to provide permission

A tenant administrator can provide permission at any time using this URL without having to go through the steps of creating a connection.

  1. Access the following URL to be directed to the Nintex website.

    2. When using the link, replace <tenantname> that is highlighted in the link with the name of your tenant. The link will only work when the correct tenant name is inserted in place of <tenantname>.

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=bf5d7851-1215-4557-b85b-e3634a44e8fa&response_type=code&redirect_uri=https://www.nintex.com&scope=https://<tenantname>.sharepoint.com/AllSites.FullControl%20 https://<tenantname>.sharepoint.com/User.Read.All%20openid%20email%20profile%20offline_access&prompt=consent&response_mode=query

  1. Sign into your tenant admin account. The following dialog box is displayed:

  1. In the dialog box, select the Consent on behalf of your organization check box.
  2. Click Accept.

If the administrator has not provided permission, one of the following messages is displayed when a workflow designer wants to create a new connection:

The following dialog box will be displayed for users who are not tenant administrators:

  • You can request your tenant administrator to provide permission through the URL provided. See Using URL.

The following dialog box will be displayed for users who are tenant administrators:

  1. In the dialog box, select the Consent on behalf of your organization check box.
  2. Click Accept.

Before you start 

Variables are placeholders that store information that changes each time the workflow runs or even during execution of a single workflow instance.

Each variable has a type that determines what values can be stored in the variable, such as a date, number, file path or a workflow user name. For example, if you want to save the name of an employee in a variable, you have to create a variable of type Text. The workflow can then store a name of the employee, such as "John," in the variable.

  • Text: Text string.
  • Boolean: Yes or No value.
  • Date/Time: Date and time value.
  • GUID: Globally unique identifier, often used to reference a list item in SharePoint.
  • Number: Integer number with decimal value.
  • Integer: Integer number with no decimal value.
  • Choice: A value that requests a selection from a list of allowed values.
  • Person or Group: A value that requests a selection from a user lookup.
  • Hyperlink: A value that requests a hyperlink URL and description.
  • Dictionary: A container that holds a single logical unit of variables. For more information, see Dictionary variables.
  • Collection: An index-based array of values, also known as an ordered list of values. For more information, see Collection variables.

In NintexOffice 365, the different categories of variables that can be used in a workflow are given below:

  • Start Variables: Workflow variables with the initiation option selected. Start Variables are used to get data from users when a workflow manually starts.

    • For more information on manually starting a workflow, see .

You can insert an existing Workflow Variable or Context Variable into the configuration fields of workflow actions A tool for building the processes, logic, and direction within workflows. and you can create user-defined variables for use throughout your workflow.

You can create user-defined variables from the Action configuration window when you are configuring a workflow action or from the toolbar of the designer page.

  1. In the Action configuration window, click in a field that accepts variables.
  2. Do one of the following depending on the method available;
    • On the drop-down list that appears, Click Create New Variable.
    • On the Insert Reference pane that appears, expand the Workflow Variables section and click Create New Variable.
  3. Do the following in the Workflow Variables pane to create the variable:
    1. For Name, type the variable name you want to use.
    2. Select a Type.
    • If you want to display the variable on the start form, select the Show on start form check box.
    1. Click Create.
  1. On the toolbar of the Designer page, click Variables. The Variables dialog box appears.
  2. Click New and fill in the following:
    1. For Name, type the variable name you want to use.
    2. For Type, select a variable type corresponding to the type of data you want to store.
    1. Click Save.

For more information, see User-defined variable types and Initiation options.

The following table describes the variable types available in the Variables dialog box as well as their initiation options, which are available when you select Yes for Initiation. Initiation options control the display and behavior of the variable on the start form that is displayed when a workflow is started manually.

Variable type Description

Initiation Available

 Initiation options
Text

Any text value.

Underlying .NET data type: System.String.

Yes
  • Multiple Lines: When selected, allows multiple text lines in the default value.
  • Description: Text to display under the text box on the start form. Example: "Enter new name".
  • Default value: Default value for variable.
Boolean

Yes or No value.

Underlying .NET data type: System.Boolean.

Yes
  • Description: Text to display under the check box on the start form. Example: "Enable?"
  • Default value: Default value for variable: Yes (true) or No (false).
Date/Time

Date and time value.

Underlying .NET data type: System.DateTime.

Yes
  • Description: Text to display under the text box on the start form. Example: "Select the date needed by".
  • Default value: Default value for variable: None or Today's date.
  • Allow blank values?: When selected, allows the start form to be submitted without specifying a value for the variable.
  • Display format: Display format for variable: Date and time or Date only.
GUID

Globally unique identifier, often used to reference a list item in SharePoint.

Underlying .NET data type: System.Guid.

No

 (n/a)
Number

Numeric with a Decimal value.

Underlying .NET data type: System.Double.

Yes
  • Description: Text to display under the text box on the start form. Example: "Specify quantity".
  • Default value: Default value for variable. Can be selected or entered.
Integer

Numeric without a decimal.

Underlying .NET data type: System.Int32.

No

 (n/a)
Choice

A value that requests a selection from a list of allowed values. The value selected by the workflow initiator is stored in the variable.

Underlying .NET data type: System.String.

Yes
  • Description: Text to display under the drop-down list on the start form. Example: "Select the product"
  • Choices: Choices available in the variable. Enter each choice on a separate line.
  • Default value: Default value for variable. Enter one of the specified choices.
Person or Group

A value that requests a selection from a user lookup. The item selected by the workflow initiator is stored in the variable.

Underlying .NET data type: System.String.

Yes
  • Description: Text to display under the text box on the start form. Example: "Select your manager"
  • Allow selection of: Scope of allowed selection: People Only or People and Groups.
  • Choose from: Source of selection: All Users or SharePoint Group. Use the drop-down list to select a SharePoint group.
  • Allow blank values?: When selected, allows the start form to be submitted without specifying a value for the variable.
  • Allow multiple values?: When selected, allows entry of multiple values.
Hyperlink

A value that requests a hyperlink URL and description.

Two text boxes are provided: 

  • Type the Web address
  • Type the description

The values entered by the workflow initiator are stored in the variable.

Underlying .NET data type: System.String.

Yes
  • Description: Text to display under the "Type the description" text box on the start form. Example: "Enter a display value for the URL"
  • Allow blank value?: When selected, allows the start form to be submitted without specifying a value for the variable.
Dictionary

A container that holds a single logical unit of variables. For more information, see Dictionary variables.

Underlying .NET data type: Microsoft.Activities.DynamicValue.

No

 (n/a)

Collection

An index-based array of values, also known as an ordered list of values. For more information, see Collection variables.

No

(n/a)

You can insert a Workflow Variable, Reference A workflow reference which is used to construct content containing information specific to the list or library item and to the current instance of the workflow. or a Context Variable into the configuration fields of workflow actions A tool for building the processes, logic, and direction within workflows..

Each field that accepts variables accepts one or more methods for inserting variables. The method available differs depending on the field.

Available methods are given below:

  • Click on the field and select an existing variable from the drop-down list for the field.

  • Click on the field, click Create New Variable, and fill the following fields in the Workflow Variable pane that appears:
    1. For Name, type the variable name you want to use.
    2. Select the Show on start form check box if you want to display the variable on the start form.
    3. Click Create.
  • Click on the field, select Workflow Variables or Workflow Context, and select a variable from the corresponding drop-down list.

  • Click Advanced Lookup, select Workflow Variables or Workflow Context from the drop-down list that appears, and then select a variable from the corresponding drop down and click Insert.

  • Click on the field that accept references and from the Insert Reference pane that appears on the right, double-click on a reference to select. Available sections and lookup values depend on the options available for the workflow action.
    Section Description
    Item Properties

    Metadata columns for the item the workflow is associated with. Available only for list workflows.
    Workflow Context

    Context variables that represent data related to the current workflow instance, such as current item or site URL and workflow name.

    • Current item URL: The URL of the item the workflow is associated item. Available only for list workflow actions.
    • Current site URL: The URL of the site the workflow is associated site.
    • Initiator login name: The login name of the person who started the workflow instance.
    • Initiator display name: The display name of the person who started the workflow instance.
    • Initiator email address: The email address of the person who started the workflow instance.
    • Instance ID: The unique identifier of the workflow instance.
    • List ID: The unique identifier of the list the workflow is associated with. Available only for list workflow actions.
    • List Name: The name of the list the workflow is associated with. Available only for list workflow actions.
    • Manager login name: The login name of the manager of the initiator (the person who started the workflow instance).
    • Manager display name: The display name of the manager of the initiator (the person who started the workflow instance).
    • Manager email address: The email address of the manager of the initiator (the person who started the workflow instance).
    • Publish user: The person who published the workflow.
    • Workflow name: The name of the executing workflow.
    Workflow Variables Workflow variables configured for the workflow.

You can configure variables to collect data when a workflow is manually started. These variables will be shown on a start form used to initiate the workflow and allows users to specify a value for the workflow variable before the workflow starts, basically passing values into the workflow before it starts.

Variables displayed on a start form are also known as the "start data" of the workflow and represent data that must be collected when the workflow is started.

Note:  If the workflow starts automatically, then default values are used for start data.

To learn how to manually start a workflow, see Start a workflow manually.

Configure a variable to show on a workflow start form:

  1. Open the required workflow. The workflow designer opens.

  2. On the toolbar, click Variables. The Variables window opens.

  3. To edit an existing variable, click the required variable. The row becomes editable.

    or

    4. To create a variable, click New on the Variables window toolbar, enter a Name, and select the Type for the variable.

  4. Select the Initiation check box for the required variable.
  1. Click Save to commit changes.

Configure the Office 365 Update Item Permissions action

In the Designer:

  1. Click the Libraries and Lists action group in the action toolbox.

    or

    Type the action name or function in the Search field at the top of the action toolbox.

  2. Drag the Office 365 Update Item Permissions action to the designer canvas.

  3. Do one of the following to open the Action configuration window:

    • Double-click the action.
    • Click on the action and then click Configure.

    See Action configuration window for more information.

  4. Enter the URL of the site that the item belongs to in Destination site URL.
  5. Select the Connection to use to connect to the SharePoint Online site.

    6. Don't have a connection yet? For information about how to create a new connection, see Create a personal connection.

  1. Specify the List name of the list that contains the item.
  2. Select an option for Items to update.
  3. Click Save.

For more information on the fields, see Office 365 Update Item Permissions action fields, buttons, and settings.

Section

Field

Description
(none) Destination site URL

The URL of the site containing the list or document library you want to use.
(none) Connection

The connection to connect to the SharePoint site to update item permissions.

  • Permissions required: Admin consent required before creating connections.
  • Connection type required:
    • SharePoint Online: Update item permissions (OAuth2)
    • SharePoint Online: Site & user administration

For more information about connections and connection types, see Connection types and Connector actions.
(none) List name

The list or document library containing the items to be updated.

(none)

Items to update

Specify which items are to be updated.

  • Query builder: Specify the scope of items to update and create a filter with a condition.
  • CAML editor: Create a more advanced query using XML encoding.

    • CAML (Collaborative Markup Language) is an XML based language for querying and updating objects such as Lists and Libraries in SharePoint. CAML retrieves items from a SharePoint object based on the conditions specified.

Query builder

Scope

Specify options to determine the scope of updates. Select one of the following options:

  • Include items in subfolders: Updates items within subfolders.
  • Include folders: Updates items in folders.

Query builder

Filters

Filter to specify which items are to be updated. Select one of the following options:

  • Update all list items permissions: Updates all items in the specified list or document library.
  • Update items only when the following is true: Updates the items when the specified filter condition is met.

    • Field

    Description
    When Column (field) from the selected list or document library.
    Operator Comparison between When and Value.
    Value The value you are looking for in the column (field) specified for When. Accepted variable types correspond to the data type of the entry for When.

To add a condition, click Add filter rule and then fill in the fields.
(none)

Inherit permissions from parent

Specify if the item permission will inherit the parent permission set (the permissions used in the library or list that contains the item).

If this is selected any other permission setting is not applied.
(none)

Remove existing permissions

Removes permissions currently set on the item before adding the new permissions.

If the item permission currently links to the parent permission set (the permissions used in the library or list that contains the item), disabling (clearing) this option causes the inherited permissions to be copied to the items.

(none)

Target

Specify the users or group that will have access to the item.

  • User: Allow access to one or more users.

    • Note: Does not support external users. To modify permissions of an item for external users, select Group as the Target.

  • Group: Allow access to one or more SharePoint groups.

(none)

User or group name

The users or groups that will have permission to access the item.

  • If User selected as Target, specify one or more email addresses.
  • If Group selected as Target, specify one or more SharePoint group names.

 

(none)

Permission

Level of permission to assign for the indicated items. Choose the Remove option in the drop down list to remove all permissions from a user or group.

The permission level selected here will be added to the existing permissions of the users, unless Remove existing permissions is selected. If Remove existing permissions is selected the current permissions of the users are removed before the new permission is given.

Select one of the following permission levels:

  • Full Control
  • Design
  • Edit
  • Contribute
  • Read
  • View Only
  • Remove

For more information about these permission levels, see understanding-permission-levels.

(none) Custom permission

Custom SharePoint permission level for the item. The selection made in the Permission field will be overruled by the Custom permission selected.

New permission levels can be created in SharePoint. To learn more, see How to create and edit permission levels.

(none)

All matched items updated

Variable to store the operation result. Returns "Yes" if all matched items were successfully updated.

(none)

List item ID

Variable to store IDs of the updated items.

(none)

List item URL

Variable to store URLs of updated items.

For more information about how to use Lookups in configuration fields, see Lookups in action configuration fields.