Pulse Software Project API API

openapi: 3.2.0
info:
  title: Pulse Public Authentication Project API
  version: 1.0.1
  description: "The Pulse API is targeted towards developers looking to automate tasks in Pulse. \n\n# Authentication\nAll endpoints in Pulse require authentication.  Legacy endpoints require only a Private API Key, while all new endpoints incorporate JSON Web Tokens.  \n\n**API Key**\nTo consume a Pulse endpoint using API Key authentication, :\n  * Contact Pulse support at support@pulsesoftware.com to enable the Pulse Public API and issue your API key.\n  * Pass the API key in the **'x-Api-Key'** header with each request.\n\nNote: It is recommended to use a User Private API key where possible, rather than the Application Private Key. When using a User API key, functionality will be restricted based on the role of the User for which the API key was generated.  See API endpoint documentation for authorised roles. \n\n**JSON Web Token (JWT)**\nTo consume a Pulse endpoint using JWT authentication:\n  * Contact Pulse support at support@pulsesoftware.com to enable the Pulse Public API and issue your API key.\n  * Request a bearer token from /pulse/jwt, passing the API key in the **'x-Api-Key'** header with the request.\n  * Pass the token issued in the **'Authorization'** header of all requests as **'bearer [token]'**\n\n**Note** Tokens will expire 60 minutes after being issued, at which point your application will need to request a new token.\n\n# Requests\nThe Pulse API follows REST principles.  Data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. Where possible, Web API uses appropriate HTTP verbs for each action.\nHTTP Verbs:\n  * **GET** Retrieves resources\n  * **POST** Creates resources\n  * **PUT** Changes and/or replaces resources or collections\n  * **DELETE** Deletes resources\n\nThe Pulse API accepts the following ISO-8601 formats for date strings:\n  * Date, Time, Timezone: e.g. \"2021-06-02T21:39:18+00:00\"\n  * Date, Time: e.g. \"2021-06-02T21:39:18Z\"\n  * Date: e.g. \"2021-06-02\"\n\n# Responses\nPulse API returns all response data as a JSON object.  \n\n# Response Status Codes\nPulse API uses the following status codes:\n  * **200** OK - Request succeeded.  Result provided in response body.\n  * **400** Bad Request - Malformed syntax.  See message body for information.\n  * **401** Unauthorised - Missing authentication (API Key or JWT).\n  * **403** Forbidden - API user is not authorised to access requested resource.\n  * **404** Not Found - Request resource does not exist.\n\n# Support\nContact support@pulsesoftware.com for any queries or issues related to this API\n"
  termsOfService: http://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    email: support@pulsesoftware.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://*.pulsesoftware.com/webservices/api
- url: http://*.pulsesoftware.com/webservices/api
tags:
- name: Project API
  description: API for managing project info in Pulse
paths:
  /project/projectexecutionfinancialsync:
    post:
      security:
      - BearerJWT: []
      tags:
      - Project API
      summary: Sends Project Component BIS data to Pulse
      description: 'Performs a bulk upsert of BIS financial information relating to specific project codes (Project Components) at the individual project execution level.

        This matches on existing Project Executions by Project Component, which have to be pre-filled in the Projects Module on the Pulse website.

        Some preliminary setup is required before this API endpoint can be consumed. Additionally, only Admin users in the Projects Module will be able to consume this API endpoint.

        Setup instructions:

        1. Contact Pulse support at support@pulsesoftware.com to enable the Pulse Public API. Make sure you follow the steps outlined in the Authentication section to enable JWT authentication.

        2. In the Projects module, navigate to the Admin page.

        3. Click ''Manage Forms''.

        4. In a form of your choice, add the new fields that you would like to populate using this API endpoint. Ensure you make a field named ''Project Component''. This field will contain the unique Project Component value required to link a Project Execution in Pulse to a BIS Financial information record.

        5. These fields will need to be linked to this API endpoint before it can be consumed. Contact Pulse support at support@pulsesoftware.com so that they can do this for you.

        6. Once the new fields have been linked to the API, navigate to the Project Executions page in the Projects module and view the details of a Project Execution you would like to update via the API.

        7. In the Project Component field you created in step 4, add the unique identifier that will link the Project Execution to a BIS financial information record.


        **Note**: if any of the linked fields are deleted and re-added, you will need to contact Pulse support (support@pulsesoftware.com) to re-link the fields to the API.


        **Authorised Roles:** *ProjectAdmin*

        '
      operationId: updateProjectComponent
      responses:
        200:
          description: OK. Request completed successfully. Please see the updatedProjectComponents list in the response for the Project Components updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProjectComponentResponse'
        400:
          description: Request completed with some validation errors. Please see response for validation errors and list of updated Project Components.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProjectComponentResponse'
        401:
          description: Missing JWT Bearer token in the Authorization header or the given JWT token is invalid.
        403:
          description: The user corresponding to the given JWT token does not have access to this module.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectComponent'
        description: BIS financial data to be added. Ensure you fill in the Project Component property of each record with the Project Component value of a Project Execution. Any fields representing the date of last update are not required in the body.
        required: true
components:
  schemas:
    UpdateProjectComponent:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/UpdateProjectComponentData'
          example:
          - Project Component: W046-100
            Description: This is a test.
            Full Year Original Budget: 447085
            Full Year Revised Budget: 111771.36
            YTD Budget: 335314.1
            YTD Commitments: 447085.46
            YTD Actuals: 765454
            Available Budget: 125412
          - Project Component: W046-101
            Description: This is also a test.
            Full Year Original Budget: 44799.1
            Full Year Revised Budget: 111999.36
            YTD Budget: 999314.1
            YTD Commitments: 499085.46
            YTD Actuals: 87765
            Available Budget: 215545
    UpdateProjectComponentData:
      type: object
      required:
      - Project Component
      properties:
        Project Component:
          type: string
          example: W046-100
    UpdateProjectComponentResponseError:
      type: object
      properties:
        error num:
          type: string
          example: '0001'
        project-component:
          type: string
          example: W046-100
        error message:
          type: string
          example: Project-Component not found in Pulse.
        error detail:
          type: string
          example: Please ensure that the Project-Component exists in Pulse.
    UpdateProjectComponentResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/UpdateProjectComponentResponseError'
          example:
          - error num: '0003'
            project-component: W046-100
            error message: Project-Component not found in Pulse.
            error detail: Please ensure that the Project-Component exists in Pulse.
          - error num: '0001'
            project-component: ''
            error message: Missing Project Component Id.
            error detail: Data must contain key 'Project Component'.
        updatedProjectComponents:
          type: array
          items:
            type: string
          example:
          - project component code 1
          - project component code 2
  securitySchemes:
    ApiKey:
      type: apiKey
      name: x-Api-Key
      in: header
    BearerJWT:
      type: apiKey
      name: Authorisation
      in: header
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io