Confluence

Confluence Command Line Interface (CLI)

Create Action File

Estimated Time: 2 min

In this step, you will be creating a text file that contains the CLI actions that will create a Confluence space and set appropriate permissions for it. This file will be invoked and executed in a later step.

1. Open an editor capable of producing a plain text file, such as Notepad (Windows) or TextEdit (Mac), and then paste in the contents shown to the right.

   1. Line 1 executes the addSpace action to create a new Confluence space using the following parameters:

      • --space defines the space key for the new space.

      • --name defines the name of the new space.

      • --description provides some explanation regarding the purpose or use of the new space.

   2. Line 2 executes the addPermissions action to grant permissions to anonymous users.

   3. Line 3 executes the addPermissions action to grant permissions to members of the confluence-users group.

   4. Line 4 executes the addPermissions action to grant permissions to members of the confluence-administrators group.

   5. Line 5 executes the addPermissions action to grant permissions to a user with the username of "joe" who, in our example, represents the person requesting the new space.

      You should replace "joe" with a userid that is defined in your JIRA instance.

   6. Lines 2 through 5 use the following parameters for the addPermissions action:

      • --space defines the space key for the new space. It is using a @space@ variable that indicates to use the last referenced space key, which would be the one on Line 1's addSpace action. You could also use the same value used on Line 1 ("newSpaceKey"), but using the variable will result in you making fewer edits when using this file again to create another new space.

      • --userId identifies the username of the user to whom permissions should be granted. This can be a specific person's username (as used on Line 5) or it can also be "anonymous" (as used on Line 2) to grant access to anonymous users. An 'anonymous user' is someone who has not logged in to the Confluence site.

      • --group identifies the group to whom permissions should be granted.

      • --permissions identifies each permission to be granted to the userId or group.

         View allowable permissions...

        Permission	Allows User to...
        COMMENT	Make comments in the space.
        CREATEATTACHMENT	Add attachments to pages in the space.
        EDITBLOG	Add blog posts in the space.
        EDITSPACE	Add pages in the space.
        EXPORTPAGE	(This option has been deprecated.)
        EXPORTSPACE	Export content from the space via the space-level export screens. Note that this permission doesn't affect the exporting of a single page's content. Anyone who has permission to view the page also has permission to export its content.
        REMOVEATTACHMENT	Delete attachments from pages in the space.
        REMOVEBLOG	Delete blog posts in the space.
        REMOVECOMMENT	Delete comments from the space.
        REMOVEMAIL	Delete individual mail items.
        REMOVEPAGE	Delete pages in the space.
        SETPAGEPERMISSIONS	Apply page-level restrictions.
        SETSPACEPERMISSIONS	Administer this space, including granting permissions to other users. This permission can't be granted to anonymous users (users who aren't logged in).
        VIEWSPACE	View content within the space, including pages, blog posts etc.

        
        

        
        

2. Save the file under the name CreateNewWikiSpace_actions.txt in the same folder to which you installed the Confluence CLI client.

Example action file:

CreateNewWikiSpace_actions.txt

--action addSpace --space "newSpaceKey" --name "newSpaceName" --description "This is the Space Description"
--action addPermissions --space "@space@" --userId "anonymous"                 --permissions "viewspace" 
--action addPermissions --space "@space@" --group  "confluence-users"          --permissions "viewspace,comment,removecomment,editspace,removepage,setpagepermissions,editblog,removeblog,createattachment,removeattachment,exportspace"
--action addPermissions --space "@space@" --group  "confluence-administrators" --permissions "viewspace,comment,removecomment,editspace,removepage,setpagepermissions,editblog,removeblog,createattachment,removeattachment,removemail,exportspace,setspacepermissions"
--action addPermissions --space "@space@" --userId "joe"                       --permissions "viewspace,comment,removecomment,editspace,removepage,setpagepermissions,editblog,removeblog,createattachment,removeattachment,removemail,exportspace,setspacepermissions"

Create Confluence CLI command

Estimated Time: 2 min

In this step, you will form the command line that will invoke the Confluence CLI to execute the action file you created in the previous step.

The command is shown to the right.

• confluence indicates to invoke the Confluence CLI client.

• The run action indicates to run actions from the file identified in the --file parameter.

Example command:

confluence --action run --file CreateNewWikiSpace_actions.txt

Execute Confluence CLI command

 Estimated Time: 1 min 

In your command window, type the command from the previous step and press Enter.

The command will run, showing the result of executing the actions defined in the CreateNewWikiSpace_actions.txt file you created earlier.

Note that Administrator rights to the new space will  automatically be given to the user whose credentials were used when running the Confluence CLI.

If you go into the Space Administration screens to look at the Space Details and Permissions screens, you should see something similar to the screenshots shown to the right.

That's it! With one command, you've created a Confluence space and saved yourself from having to complete many steps to do it!

Example output:

Run: --action addPermissions --space "newSpaceKey" --userId "anonymous"                 --permissions "viewspace"
[VIEWSPACE] permissions where added to space: 'newSpaceKey' for: 'anonymous'.
Run: --action addPermissions --space "newSpaceKey" --group  "confluence-users"          --permissions "viewspace,comment,removecomment,editspace,removepage,setpagepermissions,editblog,removeblog,createattachment,removeattachment,exportspace"
[VIEWSPACE, COMMENT, REMOVECOMMENT, EDITSPACE, REMOVEPAGE, SETPAGEPERMISSIONS, EDITBLOG, REMOVEBLOG, CREATEATTACHMENT, REMOVEATTACHMENT, EXPORTSPACE] permissions where added to space: 'newSpaceKey' for: 'confluence-users'.
Run: --action addPermissions --space "newSpaceKey" --group  "confluence-administrators" --permissions "viewspace,comment,removecomment,editspace,removepage,setpagepermissions,editblog,removeblog,createattachment,removeattachment,removemail,exportspace,setspacepermissions"
[VIEWSPACE, COMMENT, REMOVECOMMENT, EDITSPACE, REMOVEPAGE, SETPAGEPERMISSIONS, EDITBLOG, REMOVEBLOG, CREATEATTACHMENT, REMOVEATTACHMENT, REMOVEMAIL, EXPORTSPACE, SETSPACEPERMISSIONS] permissions where added to space: 'newSpaceKey' for: 'confluence-administrators'.
Run: --action addPermissions --space "newSpaceKey" --userId "joe"                       --permissions "viewspace,comment,removecomment,editspace,removepage,setpagepermissions,editblog,removeblog,createattachment,removeattachment,removemail,exportspace,setspacepermissions"
[VIEWSPACE, COMMENT, REMOVECOMMENT, EDITSPACE, REMOVEPAGE, SETPAGEPERMISSIONS, EDITBLOG, REMOVEBLOG, CREATEATTACHMENT, REMOVEATTACHMENT, REMOVEMAIL, EXPORTSPACE, SETSPACEPERMISSIONS] permissions where added to space: 'newSpaceKey' for: 'joe'.
Run completed successfully. 5 actions were successful from file: /usr/local/CLI/CreateNewWikiSpace_actions.txt

 View newly created space...

Space Details view of newly created Space:

Space Permissions of newly created Space:

Bonus Tip

 OPTIONAL Estimated Time: 2 min

You may have established one or more sets of "standard permissions" you use in your Confluence site, such as one for a personal space, one for a team space, and another for a public space open to everyone.

If this is the case, you may want to use a modified version of the CreateNewWikiSpace_actions.txt file as shown on the right.

In this modified version, Lines 2 through 5 are replaced with a single line (Line 2) that uses the copyPermissions action so that the new space is created with permissions identical to what is used in another space. The parameters used by this action are:

• --space which identifies the the space key of a space that has the permissions you want to copy

• --newSpace which uses the @space@ variable to indicate it is the newly created space to which the other space's permissions should be copied.

Modified action file:

CreateNewWikiSpace_actions.txt

--action addSpace --space "newSpaceKey" --name "newSpaceName" --description "This is the Space Description"
--action copyPermissions --space "modelspace" --newSpace "@space@"