Symphony Groups API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Symphony Profile Manager Groups API
  description: Profile Manager is a microservice to manage users profile and groups.
servers:
- url: /profile-manager
security:
- bearerAuth: []
tags:
- name: Groups
paths:
  /v1/groups/{groupId}/member:
    post:
      summary: Symphony Add a New User to a an Existing Group
      parameters:
      - in: header
        name: X-Symphony-Host
        schema:
          type: string
          description: headers to indentify the origin
          minLength: 1
          example: localhost.symphony.com
        required: true
      - in: path
        name: groupId
        schema:
          type: string
          description: Group id
          example: WzEwMF1bU0RMXVtUZXN0IEdyb3VwXQ
        required: true
      description: Add a new user to a an existing group
      operationId: addMemberToGroup
      tags:
      - Groups
      requestBody:
        $ref: '#/components/requestBodies/AddMemberRequestBody'
      responses:
        '200':
          description: Successful response. Returns the group with the new add user as a member
          headers:
            Etag:
              schema:
                type: string
                example: e3a52e72-0854-4401-8c24-e0b17c0ca304
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadGroup'
        '400':
          description: Returned if missing required parameters or wrong parameters
          $ref: ./symphony-common-definitions.yaml#/components/responses/BadRequest
        '401':
          description: Returned if wrong or missing JWT token
          $ref: ./symphony-common-definitions.yaml#/components/responses/Unauthorized
        '403':
          description: Returned if JWT token missing the required entitlement
          $ref: ./symphony-common-definitions.yaml#/components/responses/Forbidden
        '429':
          description: Returned if the backend is overloaded
          $ref: '#/components/responses/TooManyRequests'
        '452':
          description: Returned if there is a violation in info barrier rules. This error is not relevant in case of a Company group
          $ref: '#/components/responses/InfoBarrierViolation'
  /v1/groups:
    post:
      summary: Symphony Insert a New Group
      parameters:
      - in: header
        name: X-Symphony-Host
        schema:
          type: string
          description: headers to indentify the originator
          minLength: 1
          example: localhost.symphony.com
        required: true
      description: Insert a new group into database
      operationId: insertGroup
      tags:
      - Groups
      requestBody:
        $ref: '#/components/requestBodies/CreateGroupBody'
      responses:
        '201':
          description: Successful response. Returns the group just created with the new added member
          headers:
            Etag:
              schema:
                type: string
                example: e3a52e72-0854-4401-8c24-e0b17c0ca304
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadGroup'
        '400':
          description: Returned if missing required parameters, Trying to add a member which is already existing within the group list of members, or the requested user member is already a part of company group in case of a company group type
          $ref: ./symphony-common-definitions.yaml#/components/responses/BadRequest
        '401':
          description: Returned if wrong or missing JWT token
          $ref: ./symphony-common-definitions.yaml#/components/responses/Unauthorized
        '403':
          description: Returned if JWT token missing the required entitlement
          $ref: ./symphony-common-definitions.yaml#/components/responses/Forbidden
        '429':
          description: Returned if the backend is overloaded
          $ref: '#/components/responses/TooManyRequests'
        '452':
          description: Returned if there is a violation in info barrier rules. This error is not relevant in case of a Company group
          $ref: '#/components/responses/InfoBarrierViolation'
  /v1/groups/{groupId}:
    get:
      summary: Symphony Retrieve a Group
      parameters:
      - in: header
        name: X-Symphony-Host
        schema:
          type: string
          description: headers to indentify the originator
          minLength: 1
          example: localhost.symphony.com
        required: true
      - in: path
        name: groupId
        schema:
          type: string
        required: true
        description: Group id
        example: WzEwMF1bU0RMXVtUZXN0IEdyb3VwXQ
      description: Retrieve a group
      operationId: getGroup
      tags:
      - Groups
      responses:
        '200':
          description: Successful response. Returns the group
          headers:
            Etag:
              schema:
                type: string
                example: e3a52e72-0854-4401-8c24-e0b17c0ca304
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadGroup'
        '400':
          description: Returned if missing required parameters or wrong parameters
          $ref: ./symphony-common-definitions.yaml#/components/responses/BadRequest
        '401':
          description: Returned if wrong or missing JWT token
          $ref: ./symphony-common-definitions.yaml#/components/responses/Unauthorized
        '403':
          description: Returned if JWT token missing the required entitlement
          $ref: ./symphony-common-definitions.yaml#/components/responses/Forbidden
        '404':
          description: Returned if groupId is not found
          $ref: ./symphony-common-definitions.yaml#/components/responses/NotFound
        '429':
          description: Returned if the backend is overloaded
          $ref: '#/components/responses/TooManyRequests'
    put:
      summary: Symphony Update a Group
      parameters:
      - in: header
        name: X-Symphony-Host
        schema:
          type: string
          description: headers to indentify the originator
          minLength: 1
          example: localhost.symphony.com
        required: true
      - in: header
        name: If-Match
        schema:
          type: string
          description: ETag of group to be updated
          example: e3a52e72-0854-4401-8c24-e0b17c0ca304
        required: true
      - in: path
        name: groupId
        schema:
          type: string
        required: true
        description: Group id
        example: 60af77fd294165466ccdf510
      description: Update an existing group
      operationId: updateGroup
      tags:
      - Groups
      requestBody:
        $ref: '#/components/requestBodies/UpdateGroupBody'
      responses:
        '200':
          description: Successful response. Returns the group just updated
          headers:
            Etag:
              schema:
                type: string
                example: e3a52e72-0854-4401-8c24-e0b17c0ca304
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadGroup'
        '400':
          description: Returned if missing required parameters or wrong parameters
          $ref: ./symphony-common-definitions.yaml#/components/responses/BadRequest
        '401':
          description: Returned if wrong or missing JWT token
          $ref: ./symphony-common-definitions.yaml#/components/responses/Unauthorized
        '403':
          description: Returned if JWT token missing the required entitlement
          $ref: ./symphony-common-definitions.yaml#/components/responses/Forbidden
        '404':
          description: Returned if groupId is not found
          $ref: ./symphony-common-definitions.yaml#/components/responses/NotFound
        '412':
          description: The update is rejected because concurrent update
          $ref: ./symphony-common-definitions.yaml#/components/responses/PreconditionFailed
        '429':
          description: Returned if the backend is overloaded
          $ref: '#/components/responses/TooManyRequests'
        '452':
          description: Returned if there is a violation in info barrier rules. This error is not relevant in case of a Company group
          $ref: '#/components/responses/InfoBarrierViolation'
  /v1/groups/{groupId}/avatar:
    post:
      summary: Symphony Update the Group Avatar
      parameters:
      - in: header
        name: X-Symphony-Host
        schema:
          type: string
          description: headers to indentify the originator
          minLength: 1
          example: localhost.symphony.com
        required: true
      - in: path
        name: groupId
        schema:
          type: string
        required: true
        description: Group id
        example: 60af77fd294165466ccdf510
      description: Update the group account avatar
      operationId: updateAvatar
      tags:
      - Groups
      requestBody:
        $ref: '#/components/requestBodies/UpdateAvatar'
      responses:
        '200':
          description: Successful response. Returns the group with the avatar updated
          headers:
            Etag:
              schema:
                type: string
                example: e3a52e72-0854-4401-8c24-e0b17c0ca304
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadGroup'
        '400':
          description: Returned if missing required parameters or wrong parameters
          $ref: ./symphony-common-definitions.yaml#/components/responses/BadRequest
        '401':
          description: Returned if wrong or missing JWT token
          $ref: ./symphony-common-definitions.yaml#/components/responses/Unauthorized
        '403':
          description: Returned if JWT token missing the required entitlement
          $ref: ./symphony-common-definitions.yaml#/components/responses/Forbidden
        '404':
          description: Returned if groupId is not found
          $ref: ./symphony-common-definitions.yaml#/components/responses/NotFound
        '429':
          description: Returned if the backend is overloaded
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    addMember:
      properties:
        member:
          $ref: '#/components/schemas/Member'
    Status:
      type: string
      enum:
      - ACTIVE
      - DELETED
      description: Status flag to distinguish between active and deleted objects
      example: ACTIVE
    Owner:
      type: string
      enum:
      - PLATFORM
      - TENANT
      - USER
      description: Owner type. Ony TENANT supported now
      example: TENANT
    UpdateGroup:
      allOf:
      - $ref: '#/components/schemas/CreateGroup'
      - type: object
        required:
        - rootCause
        properties:
          id:
            type: string
            description: Group's unique identifier
            minLength: 1
            example: 60af77fd294165466ccdf510
          status:
            $ref: '#/components/schemas/Status'
          eTag:
            type: string
            example: e3a52e72-0854-4401-8c24-e0b17c0ca304
            minLength: 1
    Avatar:
      properties:
        size:
          type: string
        url:
          type: string
    BaseProfile:
      description: The group's profile. Please note that in case of a company group type, the profile shouldn't be provided when creating a new company and do not exist in case of an existing company group
      properties:
        displayName:
          type: string
          description: The display name in Directory, it is expected to be the same as group name
          minLength: 1
          example: Test Group
        companyName:
          type: string
          description: The company name is expected to be the same as group company owner
          example: Acme Corporation
        email:
          type: string
          example: testgroup@acme.com
        mobile:
          type: string
          example: +33(0)600000000
        jobTitle:
          type: string
        jobRole:
          type: string
          example: Director
        jobDepartment:
          type: string
        jobDivision:
          type: string
        jobPhone:
          type: string
        jobCity:
          type: string
        industryOfInterest:
          type: array
          items:
            type: string
          example:
          - Services
        assetClassesOfInterest:
          type: array
          items:
            type: string
          example:
          - Equities
        marketCoverage:
          type: array
          uniqueItems: true
          items:
            type: string
          example:
          - EMEA
        responsibility:
          type: array
          uniqueItems: true
          items:
            type: string
          example:
          - Escalation
        function:
          type: array
          uniqueItems: true
          items:
            type: string
          example:
          - Collateral
        instrument:
          type: array
          uniqueItems: true
          items:
            type: string
          example:
          - Equities
    GroupInteractionTransfer:
      description: Group interaction transfer.
      properties:
        restrictedTenantsList:
          type: array
          items:
            type: integer
          example:
          - 100
        restrictedUsersList:
          type: array
          items:
            type: integer
            format: int64
          example:
          - 12345678900000
    Member:
      description: A Group member.
      properties:
        memberTenant:
          type: integer
          description: Member's tenant id
          example: 100
        memberId:
          type: integer
          format: int64
          description: Member's user id
          example: 12345678900000
    GroupVisibilityRestriction:
      description: Group visibility restriction.
      properties:
        restrictedTenantsList:
          type: array
          items:
            type: integer
          example:
          - 100
        restrictedUsersList:
          type: array
          items:
            type: integer
            format: int64
          example:
          - 12345678900000
    UploadAvatar:
      properties:
        image:
          type: string
          format: byte
          description: 'The avatar image for the user profile picture.The image must be a base64-encoded .jpg, .png, or .gif. >- Image size limit: 2 MB'
    ReadMember:
      allOf:
      - $ref: '#/components/schemas/Member'
      - type: object
        required:
        - rootCause
        properties:
          addedDate:
            description: Date/time when the member has been added in the group in ISO-8601 format (YYYY-MM-DDThh:mm:ss.sZ)
            type: string
            format: date-time
          status:
            description: Some group types (e.g. COMPANY) keep disabled users, flagging them as DISABLED. However, this attribute is not relevant for group types (e.g. SDL) that remove (instead of flag) disabled user from group
            type: string
            enum:
            - ENABLED
            - DISABLED
            example: ENABLED
    ReadGroup:
      allOf:
      - $ref: '#/components/schemas/BaseGroup'
      - type: object
        required:
        - rootCause
        properties:
          id:
            type: string
            description: Group's unique identifier
          createdDate:
            type: string
            format: date-time
          createdBy:
            type: string
          updatedDate:
            type: string
            format: date-time
          updatedBy:
            type: string
          status:
            $ref: '#/components/schemas/Status'
          eTag:
            type: string
            example: e3a52e72-0854-4401-8c24-e0b17c0ca304
          subType:
            type: string
            enum:
            - COMMUNITY
            - CHANNEL
            description: The type of the company group, This field is mandatory in case of a company group type, but not applicable for Symphony Distribution List
            example: COMMUNITY
          referrer:
            type: string
            description: The referring company name. This field is mandatory in case of a company group type, but not applicable for Symphony Distribution List
            example: Symphony, referring company name, referring channel partner name
          members:
            type: array
            items:
              $ref: '#/components/schemas/ReadMember'
          profile:
            $ref: '#/components/schemas/Profile'
            description: The profile is not supported for company group, but only works with SDL as group type
          visibilityRestriction:
            $ref: '#/components/schemas/GroupVisibilityRestriction'
          implicitConnection:
            $ref: '#/components/schemas/GroupImplicitConnection'
          interactionTransfer:
            $ref: '#/components/schemas/GroupInteractionTransfer'
    CreateGroup:
      allOf:
      - $ref: '#/components/schemas/BaseGroup'
      - type: object
        required:
        - rootCause
        properties:
          subType:
            type: string
            enum:
            - COMMUNITY
            - CHANNEL
            description: The type of the company group, This field is mandatory in case of a company group type, but not applicable for Symphony Distribution List
            example: COMMUNITY
          referrer:
            type: string
            description: The referring company name. This field is mandatory in case of a company group type, but not applicable for Symphony Distribution List
            example: Symphony, referring company name, referring channel partner name
          members:
            type: array
            items:
              $ref: '#/components/schemas/Member'
          profile:
            $ref: '#/components/schemas/BaseProfile'
            description: The profile is not supported for company group, but only works with SDL as group type
            required: true
          visibilityRestriction:
            $ref: '#/components/schemas/GroupVisibilityRestriction'
          implicitConnection:
            $ref: '#/components/schemas/GroupImplicitConnection'
          interactionTransfer:
            $ref: '#/components/schemas/GroupInteractionTransfer'
    Profile:
      allOf:
      - $ref: '#/components/schemas/BaseProfile'
      - type: object
        required:
        - rootCause
        properties:
          id:
            type: string
            description: Profile unique identifier
          avatars:
            type: array
            items:
              $ref: '#/components/schemas/Avatar'
    BaseGroup:
      description: A reduced set Group object, for retrieving list of group purpose
      properties:
        type:
          type: string
          minLength: 1
          description: Group type identifier
          example: SDL
        ownerType:
          $ref: '#/components/schemas/Owner'
        ownerId:
          type: integer
          format: int64
          description: Owner id if the owner type is tenant (podId) or user (userId), otherwise null
          example: 100
        name:
          type: string
          minLength: 1
          description: Group's name
          example: Test Group
      required:
      - type
      - ownerType
      - ownerId
      - name
    GroupImplicitConnection:
      description: Group implicit connections.
      properties:
        connectedTenantsList:
          type: array
          items:
            type: integer
          example:
          - 100
        connectedUsersList:
          type: array
          items:
            type: integer
            format: int64
          example:
          - 12345678900000
  requestBodies:
    UpdateAvatar:
      description: JSON object containing Group avatar
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UploadAvatar'
    UpdateGroupBody:
      description: JSON object containing Group info
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateGroup'
    CreateGroupBody:
      description: JSON object containing Group info
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateGroup'
    AddMemberRequestBody:
      description: JSON object containing the user member information and the group on which he will be added to
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/addMember'
  responses:
    TooManyRequests:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: ./symphony-common-definitions.yaml#/components/schemas/Error
    InfoBarrierViolation:
      description: Info barrier violation found between group account's members.
      content:
        application/json:
          schema:
            $ref: ./symphony-common-definitions.yaml#/components/schemas/Error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Use Common JWT