Breadcrumbs

REST API

Additionally to copying templates by invoking PTC via Confluences web UI, it is also possible to utilize PTC's own REST API for this purpose.

Note: This API might be subject to change. Use with caution and conduct necessary tests of your systems before updating to a newer version of Page Tree Creator!

Template copying procedure

To start the copying process, execute a POST request to PTC's /instantiation web resource. Attach the necessary JSON document as the body to the request, as further specified below. Keep in mind that not all fields in the PlaceholderDto are necessarily required, only the ones needed for the specific placeholder type.

If the request was processed successfully, PTC will return a response containing a taskId which is necessary to monitor the progress of the page copying process via Confluences Long Running Task API. Once the process has completed, execute a GET request to PTC's /completed web resource, including the taskId in the request. PTC will respond with the outcome of the copying process, and if successful, include the URL to the newly created page in the response.

This API was published on special request from some of our customers and the specification might be incomplete. If you need further assistance, feel free to get in touch with our support via our service desk or via E-Mail at apps@eps-support.ch

For simple tests, you can use Postman to test your CRUD operations.

Page Tree Creator v8

[ Base URL: /rest/treecreator/1.0 ]

Placeholder search (DEPRECATED)

GET instantiations/placeholders/{sourcePageId}

Click to expand...

The procedure (long running task, task handle) for querying this resource is the same as for the instantiation resource.

The creationType query parameter accepts the same values as in the instantiation resource.

Parameters

Name

Description

sourcePageId *required

(path)

Id of the Page, that you would like to copy.

targetSpaceKey *required

(query)

Key of the Space, on which your target page is located.

targetPageId *required

(query)

Id of your target page

(this would be the new root page)

currentPageId

(query)

Current page id

(For example where the button is located)

unselectedPages

(query)

Id’(s) of the page(s) which should not be copied to the target page tree.

Note: page ids as an array (comma separated)

creationType *required

(query)

on of the following types:

[ CREATE_PAGE_TREE, CREATE_SPACE, COPY_SPACE ]

  • Create Page Tree → Create new page tree with placeholder replacement.

  • Create Space → Create new Space with placeholder replacement.

  • Copy Space → Just copy space no placeholder will be replaced.

Response

Code

Description

200

OK

{
  "taskId": "string"
}

Placeholder search (new since PTC v. 8.7.0)

POST /placeholderSearch/{sourcePageId}

Parameters

Name

Description

Body *required

(body)

body as application/json

See Placeholder Search Body Example and Model

Response

Code

Description

200

OK

{
  "taskId": "string"
}

Placeholder Search Body Example

{
  "targetSpaceKey": "string",
  "targetPageId": 0,
  "currentPageId": 0,
  "unselectedPages": [
    1001,
    1002
  ],
  "labels": [
    "label1",
    "label2"
  ],
  "creationType": "CREATE_PAGE_TREE"
}

Template Instantiation

POST /instantiations

Parameters

Name

Description

Body *required

(body)

body as application/json

See Instantiation Body Example and Model

Response

Code

Description

200

OK

{
  "taskId": "string"
}

Page Instantiation Body Example

{
  "sourcePageId": 0,
  "type": "page",
  "creationType": "CREATE_PAGE_TREE",
  "jumpIntoEdit": true,
  "pagesToWatch": "MAIN",
  "resolvePageTitles": true,
  "labels": [
    "string"
  ],
  "tagReplacements": [
    {
      "tag": "__placeholder__",
      "placeholderType": "STANDARD",
      "replacement": "string",
      "replacements": [
        "string"
      ],
      "errorMessages": [
        "string"
      ],
      "id": 0,
      "required": true,
      "linkText": "string",
      "userSeparator": "string",
      "dropdownSeparator": "string",
      "countupLocation": "string",
      "counterPrefix": "string",
      "counterPostfix": "string",
      "counterNumberOfDigits": 0,
      "currentCount": 0
    }
  ],
  "targetPageId": 0,
  "targetSpaceKey": "string",
  "unselectedPages": [
    0
  ],
  "copyOptions": {
      "copyAttachments": true,
      "copyLabels": true,
      "copyRestrictions": true
  }
}

Response

Code

Description

200

OK

{
  "taskId": "string"
}

YAML

YAML 
swagger: '2.0'
info:
  version: 8.0.0
  title: PageTreeCreator
basePath: /rest/treecreator/1.0

paths:
  '/instantiations':
    post:
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/TemplateInstantiationDto'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TaskHandle'
            
  '/completed/{taskId}':
    get:
      consumes: []
      produces:
        - application/json
      parameters:
        - type: string
          name: taskId
          in: path
          required: true
      responses:
        '204':
          description: No Content
          headers: {}
          
          
definitions:
  TemplateInstantiationDto:
    properties:
      sourcePageId:
        type: integer
      type:
        type: string
        enum: [page,space]
      creationType:
        type: string
        enum: [CREATE_PAGE_TREE,CREATE_SPACE,COPY_SPACE]
      jumpIntoEdit:
        type: boolean
      labels:
        type: string
      pagesToWatch:
        type: string
        enum: [MAIN,NONE,ALL]
      resolvePageTitles:
        type: boolean
      tagReplacements:
        type: array
        items:
          $ref: '#/definitions/PlaceholderDto'
      targetPageId:
        type: integer
      targetSpaceKey:
        type: string
      unselectedPages:
        type: array
        items:
          type: integer
          
  PlaceholderDto:
    properties:
      tag:
        type: string
      placeholderType:
        type: string
        enum: [STANDARD,USER,CONSECUTIVE,CASCADED,DATE,TIME,REGEX,COUNTER,MULTIUSER,MULTILINE,INSIGHT,MULTIDROPDOWN,DROPDOWN, LINK, PAGE]
      replacement:
        type: string
      replacements:
        type: array
        items:
          type: string
      errorMessages:
        type: array
        items:
          type: string
      id:
        type: integer
      required:
        type: boolean
      linkText:
        type: string
      userSeparator:
        type: string
      dropdownSeparator:
        type: string
      countupLocation:
        type: string
      counterPrefix:
        type: string
      counterPostfix:
        type: string
      counterNumberOfDigits:
        type: integer
      currentCount:
        type: integer
        
  TaskHandle:
    properties:
      taskId:
        type: string

Completed

GET /completed/{taskId}

Use the Response from the Placeholder Search and Template Instantiation (task-id) for:

  • Placeholder Search: To get all the placeholders found by the placeholder search (/instantiations/placeholderSearch/{sourcePageId})

  • Template Instantiation: To track the process of the Page Creation (/instantiations)

Parameters

Name

Description

taskId *required

string

(path)

taskId (response from /instantiations)

Response

Code

Description

200

OK

Placeholder Search TaskId:

  • Array with found placeholders

    [
    {
        "id": "af886fb2-1ad9-4000-be59-d966a81631a1",
        "tag": "__Placeholder__",
        "required": false,
        "placeholderType": "STANDARD",
        "reuseReplacement": false,
        "editableOnReuse": false,
        "counterNumberOfDigits": 0,
        "currentCount": 0,
        "displayedTag": "Placeholder",
        "defaultTag": false,
        "isEditable": true,
        "useDefaultValue": false,
        "jiraAutomationRequired": false,
        "isDynamicField": false,
        "isStaticField": false,
        "dynamicField": false,
        "staticField": false,
        "editable": true
    }
]

Template Instantiation TaskId:

  • URL to created page (root-page)

    {
  url : string
}

YAML

YAML 
openapi: "3.0.3"
info:
  version: 8.0.0
  title: PageTreeCreator
basePath: /rest/treecreator/1.0

paths:
  /instantiations/placeholders/{sourcePageId}:
    get:
      summary: "GET instantiations/placeholders/{sourcePageId}"
      parameters:
      - name: "sourcePageId"
        in: "path"
      - name: "targetSpaceKey"
        in: "query"
      - name: "targetPageId"
        in: "query"
      - name: "currentPageId"
        in: "query"
      - name: "unselectedPages"
        in: "query"
      - name: "labels"
        in: "query"
      - name: "creationType"
        in: "query"
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TaskHandle'

Models

TemplateInstantiationDto 
TemplateInstantiationDto  {
  sourcePageId	       integer
  type	               string
                        Enum:
                        [ page, space ]
  creationType	      string
                        Enum:
                        [ CREATE_PAGE_TREE, CREATE_SPACE, COPY_SPACE ]
  jumpIntoEdit	      boolean
  labels	          string
  pagesToWatch	      string
                        Enum:
                        [ MAIN, NONE, ALL ]
  resolvePageTitles   boolean
  tagReplacements	  [ PlaceholderDto {
                            tag	string
                            placeholderType	        string
                                                        Enum:
                                                        [ STANDARD, USER, CONSECUTIVE,
                                                        CASCADED, DATE, TIME, REGEX,
                                                        COUNTER, MULTIUSER, MULTILINE,
                                                        INSIGHT, MULTIDROPDOWN, DROPDOWN,
                                                        LINK, PAGE, ADVANCED_DROPDOWN ]
                            replacement	            string
                            replacements	        [string]
                            errorMessages	        [string]
                            id	                    integer
                            required	            boolean
                            linkText	            string
                            userSeparator	        string
                            dropdownSeparator       string
                            countupLocation         string
                            counterPrefix	        string
                            counterPostfix	        string
                            counterNumberOfDigits	integer
                            currentCount	        integer
                      }]
  targetPageId	      integer
  targetSpaceKey	  string
  unselectedPages	  [integer]
  copyOptions         [ PageCopyOptionsDto || SpaceCopyOptionsDto ]
}
PageCopyOptionsDto 
PageCopyOptionsDto {
  copyAttachments       boolean
  copyLabels            boolean
  copyRestrictions      boolean
}
SpaceCopyOptionsDto 
SpaceCopyOptionsDto {
  copySpaceFavorite:    boolean
  copyPageFavorite:     boolean
  copyPageTemplate:     boolean
  copySpacePermissions: boolean
  createPersonalSpace:  boolean
  copySpaceAvatar:      boolean
}
PlaceholderDto 
PlaceholderDto  {
  tag	                 string
  placeholderType	     string
                            Enum:
                            [ STANDARD, USER, CONSECUTIVE,
                            CASCADED, DATE, TIME, REGEX,
                            COUNTER, MULTIUSER, MULTILINE,
                            INSIGHT, MULTIDROPDOWN, DROPDOWN,
                            LINK, PAGE, ADVANCED_DROPDOWN ]
  replacement	         string
  replacements	         [string]
  errorMessages	         [string]
  id	                 integer
  required	             boolean
  linkText	             string
  userSeparator	         string
  dropdownSeparator	     string
  countupLocation	     string
  counterPrefix	         string
  counterPostfix	     string
  counterNumberOfDigits	 integer
  currentCount	         integer
}
TaskHandle 
TaskHandle  {
  taskId	string
}