swagger: '2.0'
info:
  description: >-
    The Notification API allows developers to manage and utilize the operations related to notification messages, namely 
    
      1. Registration of mobile apps and mobile app installation instances for receiving push notifications
      2. Sending push notifications to set of users of a mobile app; addressed either by email address or the mobile app instances.
      3. Sending emails to a set of target recipients with an option to attach files.
      4. Error with HTTP status code 400 - "Invalid property" will be applicable for all operations, wherever applicable.
      
    ## Limitations
      
      - This API cannot be accessed by subtenants.
      - The service may decide to throttle API requests temporarily returning a 429 status code.
      
    ## Generic Errors
      The following generic error codes might occur at any of the specified operation.Generic errors are prefixed with 'mdsp.core.generic.'.
      - 204: noContent
      - 400: invalidParameter
      - 400: invalidRequestBodyProperty
      - 400: missingParameter
      - 400: missingRequestBodyProperty
      - 401: unauthorized
      - 403: forbidden
      - 404: noMatch
      - 409: conflict
      - 429: tooManyRequests
      - 500: internalServerError
    See the MindSphere API documentation generic errors page for more information.
      
  version: '4.2.0'
  x-visibility: external
  title: Notification API
basePath: /api/notification/v4
produces:
  - application/json
consumes:
  - application/json
schemes:
  - https
tags:
  - name: Email Notifications
    description: >-
      Operations to send emails with optional attachments, to target recipients.
  - name: SMS Notifications
    description: >-
      Operations to send sms notifications to target recipients.
  - name: Push Notifications
    description: >-
      Operations to send push notifications to mobile apps. 
  - name: Mobile Apps
    description: >-
      Operations to define mobile apps and instances for push notifications.

securityDefinitions:
  mobilepush:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'
    scopes:
      nose.pn.r: Read push notification jobs
      nose.pn.w: Create push notification jobs
  mobileapps:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'
    scopes:
      nose.ma.r: Read mobile app registrations
      nose.ma.w: Create, update and delete mobile app registrations
  appInstances:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'
    scopes:
      nose.ai.r: Read mobile app instance registrations
      nose.ai.w: Create, update and delete mobile app instance registrations
  email:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'
    scopes:
      nose.em.r: Read email notification jobs
      nose.em.w: Create email notification jobs
  sms:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'
    scopes:
      nose.sm.r: Read SMS notification jobs
      nose.sm.w: Send SMS notification.

paths:
  /multicastSMSNotificationJobs:
    post:
      tags:
        - SMS Notifications
      security:
        - sms:
          - nose.sm.w
      summary: Sends an SMS notification to specified recipients.
      description: "<p> Publishes the notification via sms to the specified recipients. The message is scanned for any vulnerabilities before dispatching it to the recipients. A single SMS message can contain up to 140 bytes of information where-in the character quota depends on the encoding scheme. For example, an SMS message can contain: </p>
        <li>	160 GSM characters </li>
        <li>	140 ASCII characters </li>
        <li>	70 UCS-2 characters </li>
      <p> If the message size exceeds 140 bytes, it will be split into multiple messages and sent. When message is split into multiple messages, each partial message will be billed as a sinlge unit. Eg. If a message size is 200 bytes; then this it be billed as 2 units. Maximum size limit for a message is 1500 bytes.</p>"
      operationId: createSMSNotificationJob
      consumes:
        - application/json
      parameters:
        - in: body
          name: metadata
          required: true
          schema: 
            $ref: '#/definitions/MulticastSMSNotificationJobRequest'
      responses:
        '202':
          description: The notification has been successfully queued for dispatch via SMS.
          schema:
            $ref: '#/definitions/SMSJobResponse'
        '400':
          description: |
            Bad request. Possible errors:
            <br>
            <table>
              <colgroup>
                <col span="1" style="width: 30%;">
                <col span="1" style="width: 70%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message (parameterized)</th>
              </tr>
              <tr>
                <td>smsSizeLimit</td>
                <td>SMS message exceeded maximum size limit</td>
              </tr>
              <tr>
                <td>maliciousMessage</td>
                <td>SMS message contains malicious content.</td>
              </tr>
            </table>
          schema:
            $ref: '#/definitions/Errors'
        'default':
          description: Other error with any status code and response body format.
  /multicastSMSNotificationJobs/{id}:
    get:
      tags:
        - SMS Notifications
      security:
        - sms:
          - nose.sm.r
      summary: Shows status of an sms job.
      description: Shows the status of the triggered multicast sms notification job. 
      operationId: getSMSNotificationJobs
      parameters: 
        - name: id
          in: path
          description: Job ID to fetch the details
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/MulticastSMSNotificationJob'
        '404':
          description: |
            Not found. Possible errors:
            <br>
            <table>
              <colgroup>
                <col span="1" style="width: 30%;">
                <col span="1" style="width: 70%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message (parametrized)</th>
              </tr>
              <tr>
                <td>jobNotFound</td>
                <td>No job found for given ID.</td>
              </tr>
            </table>  
          schema:
            $ref: '#/definitions/Errors'
        'default':
          description: Other error with any status code and response body format.
  /multicastSMSNotificationJobs/{id}/deliveries:
    get:
      tags:
        - SMS Notifications
      security:
        - sms:
          - nose.sm.r
      summary: Shows detailed delivery information of an sms job.
      description: Shows per recipent status of sms dispatch. 
      operationId: getSMSDeliveryStatus
      parameters: 
        - name: id
          in: path
          description: Job ID to fetch the details
          required: true
          type: string
        - $ref: '#/parameters/page'
        - $ref: '#/parameters/size'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/NotificationDispatchStatusSMS'
        '404':
          description: |
            Not found. Possible errors:
            <br>
            <table>
              <colgroup>
                <col span="1" style="width: 30%;">
                <col span="1" style="width: 70%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message (parametrized)</th>
              </tr>
              <tr>
                <td>jobNotFound</td>
                <td>No job found for given ID.</td>
              </tr>
            </table>  
          schema:
            $ref: '#/definitions/Errors'
        'default':
          description: Other error with any status code and response body format. 
  /multicastEmailNotificationJobs:
    post:
      tags:
        - Email Notifications
      security:
        - email:
          - nose.em.w
      summary: Sends an email notification to specified recipients with an option to attach files.
      description: Publishes the notification via email to the specified recipients, along with attachments as optional. Maximum 5 files can be uploaded as attachments; where-in the total size of all attachments is limited to 8MB. Only zip, csv, pdf and json file types are supported as attachments. 
      operationId: createEmailNotificationJob
      consumes:
        - multipart/form-data
      parameters:
        - name: metadata
          in: formData
          required: true
          type: string
          format: json
          description: |
            See model definitions/MulticastEmailNotificationRequestMetadata. Content type must be <application/json>. The size of this attribute is limited to 250KB.
            ```
            {
                "subject": "[Status] Machine Data Analysis",
                "message": "Machine data analysis completed. Analysis report attached with this email.",
                "fromApplication": "MachineMonitor",
                "priority": "Normal",
                "recipients": [ 
                  "plantengineer@mdspcustomer.com",
                  "plantmanager@mdspcustomer.com"
                ]
            }
            ```
        - name: attachment
          description: File to be uploaded as attachment in email notification. This parameter must be provided for each file to be attached with the email. Maximum 5 files can be attached with one email request.
          in: formData
          type: string
          format: binary
      responses:
        '202':
          description: The notification has been successfully queued for dispatch via Email.
          schema:
            $ref: '#/definitions/EmailJobResponse'
        '400':
          description: |
            Bad request. Possible errors:
            <br>
            <table>
              <colgroup>
                <col span="1" style="width: 30%;">
                <col span="1" style="width: 70%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message (parameterized)</th>
              </tr>
              <tr>
                <td>emailsizeLimit</td>
                <td>Email message exceeded maximum size limit</td>
              </tr>
              <tr>
                <td>attachmentCountLimit</td>
                <td>Email attachments exceeded maximum count limit</td>
              </tr>
              <tr>
                <td>attachmentSizeLimit</td>
                <td>Email attachments exceeded maximum size limit</td>
              </tr>
              <tr>
                <td>maliciousMessage</td>
                <td>Email message contains malicious content.</td>
              </tr>
            </table>
          schema:
            $ref: '#/definitions/Errors'
        'default':
          description: Other error with any status code and response body format.
  /multicastEmailNotificationJobs/{id}:
    get:
      tags:
        - Email Notifications
      security:
        - email:
            - nose.em.r
      summary: Shows status of an email job.
      description: Shows the status of the triggered multicast email notification job. 
      operationId: getEmailNotificationJobs
      parameters: 
        - name: id
          in: path
          description: Job ID to fetch the details
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/MulticastEmailNotificationJob'
        '404':
          description: |
            Not found. Possible errors:
            <br>
            <table>
              <colgroup>
                <col span="1" style="width: 30%;">
                <col span="1" style="width: 70%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message (parametrized)</th>
              </tr>
              <tr>
                <td>jobNotFound</td>
                <td>No job found for given ID.</td>
              </tr>
            </table>  
          schema:
            $ref: '#/definitions/Errors'
        'default':
          description: Other error with any status code and response body format.       
  /multicastEmailNotificationJobs/{id}/deliveries:
    get:
      tags:
        - Email Notifications
      security:
        - email:
            - nose.em.r
      summary: Shows detailed delivery information of an email job.
      description: Shows per recipent status of email dispatch status. 
      operationId: getEmailDeliveryStatus
      parameters: 
        - name: id
          in: path
          description: Job ID to fetch the details
          required: true
          type: string
        - $ref: '#/parameters/page'
        - $ref: '#/parameters/size'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/NotificationDispatchStatus'
        '404':
          description: |
            Not found. Possible errors:
            <br>
            <table>
              <colgroup>
                <col span="1" style="width: 30%;">
                <col span="1" style="width: 70%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message (parametrized)</th>
              </tr>
              <tr>
                <td>jobNotFound</td>
                <td>No job found for given ID.</td>
              </tr>
            </table>  
          schema:
            $ref: '#/definitions/Errors'
        'default':
          description: Other error with any status code and response body format.            
  /multicastPushNotificationJobs:
    post:
      tags:
        - Push Notifications
      security:
        - mobilepush:
            - nose.pn.w
      summary: Sends a push notification to selected mobile app instances.
      description: Publishes the notification via Mobile Push to the selected mobile app instances. The developer can choose to address recipients using their mobile device ids or using the recipient's email address. When a recipient is addressed using their email address, the Notification Service sends the notifications to all app instances registered with that email address.
      operationId: createMobileAppNotificationJob
      parameters:
        - name: Job
          in: body
          required: true
          schema:
            $ref: '#/definitions/MulticastPushNotificationJobsRequest'
      responses:
        '202':
          description: The notification has been successfully queued for dispatch via mobile push.
          schema:
            $ref: '#/definitions/SendResponse'
        '400':
          description: |
            Bad request. Possible errors:
            <br>
            <table>
              <colgroup>
                <col span="1" style="width: 30%;">
                <col span="1" style="width: 70%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message (parametrized)</th>
              </tr>
              <tr>
                <td>messageEnglishLanguageMissing</td>
                <td> Default language 'English (en)' not specified in message</td>
              </tr>
            </table>  
          schema:
            $ref: '#/definitions/Errors'
        'default':
          description: Other error with any status code and response body format.
           
  /mobileApps:
    post:
      tags:
        - Mobile Apps

      security:
        - mobileapps:
          - nose.ma.w
      summary: Register a new mobile app. 
      description: A mobile app developer should use this api to register a mobile app with the Notification Service. This resource represents a mobile app in Notification Service. Either an iOS or Android configuration can be chosen for the app. Registration of the mobile app allows the developer to configure necessary push notification provider credentials.
        App Configuration details are masked and not displayed in response owing to security reasons.
      operationId: createMobileApp
      parameters:
        - name: appData
          in: body
          required: true
          schema:
            $ref: '#/definitions/AppRegistrationRequest'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/AppRegistrationResponse'
        '400':
          description: |
            Bad request. Possible errors:
            </br><table>
              <colgroup>
                <col span="1" style="width: 30%;">
                <col span="1" style="width: 5%;">
                <col span="1" style="width: 65%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left"></th>
                <th align="left">Message</th>
              </tr>
              <tr>
                <td>mobileAppTypeMismatch</td>
                <td></td>
                <td>The value of request body property type must match the additionally provided property ios or android.</td>
              </tr>
              <tr>
                <td>invalidAndroidAppCredentials</td>
                <td></td>
                <td>The value of request body property android.fcmServerKey is not valid</td>
              </tr>
              <tr>
                <td>invalidIosAppCredentials</td>
                <td></td>
                <td>The value of request body property for FCM/APNS credentials are invalid.</td>
              </tr>
            </table>
          schema:
            $ref: '#/definitions/Errors'            
        'default':
          description: Other error with any status code and response body format.
          
    get:
      tags:
        - Mobile Apps
      security:
        - mobileapps:
          - nose.ma.r
      summary: Show all registered apps for a tenant. App Configuration details are masked and not displayed in response owing to security reasons.
      operationId: queryMobileApps
      parameters:
        - $ref: '#/parameters/page'
        - $ref: '#/parameters/size'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/PagedAppRegistrationResponse'
        'default':
          description: Other error with any status code and response body format.
          
  /mobileApps/{id}:
    patch:
      tags:
        - Mobile Apps
      security:
        - mobileapps:
          - nose.ma.w
      summary: Edit a registered mobile app. App Configuration details are masked and not displayed in response owing to security reasons.
      operationId: patchMobileApp
      parameters:
        - name: id
          in: path
          description: ID of app to edit
          required: true
          type: string
        - name: appData
          in: body
          required: true
          schema:
            $ref: '#/definitions/AppRegistrationUpdateRequest'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AppRegistrationResponse'
        '400':
          description: |
            Bad request. Possible errors:
            </br><table>
              <colgroup>
                <col span="1" style="width: 30%;">
                <col span="1" style="width: 5%;">
                <col span="1" style="width: 65%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left"></th>
                <th align="left">Message</th>
              </tr>
              <tr>
                <td>appTypeCredentialMismatch
                </td>
                <td></td>
                <td>The value of request body property ios/android must match the type of app.
                </td>
              </tr>
              <tr>
                <td>invalidAndroidAppCredentials</td>
                <td></td>
                <td>The value of request body property android.fcmServerKey is not valid</td>
              </tr>
              <tr>
                <td>invalidIosAppCredentials</td>
                <td></td>
                <td>The value of request body property for FCMAPNS credentials are invalid.</td>
              </tr>
              <tr>
                <td>appCredentialMismatch</td>
                <td></td>
                <td>Provided App credentials does not match with app type.</td>
              </tr>
              <tr>
                <td>iosCredentialMismatch</td>
                <td></td>
                <td>Provided credentials does not match with existing iOS credential type.</td>
              </tr>
            </table>
          schema:
            $ref: '#/definitions/Errors'             
        'default':
          description: Other error with any status code and response body format.
          
    delete:
      tags:
        - Mobile Apps
      security:
        - mobileapps:
          - nose.ma.w
      summary: Deregister an existing registered mobile app.
      description: Deregistration of a mobile app involves deletion of all saved credentials and other configuration. Any pending notification jobs which depend on this configuration will be terminated, marked with a **failed** status and the notifications will not be dispatched to the intended recipients.
      operationId: deleteMobileApp
      parameters:
        - name: id
          in: path
          description: ID of app to delete
          required: true
          type: string
      responses:
        '204':
          description: No content
        'default':
          description: Other error with any status code and response body format.

  /mobileApps/{id}/instances:
    post:
      tags:
        - Mobile Apps
      security:
        - appInstances:
          - nose.ai.w
      summary: Registers a new mobile installation instance with a registered mobile app. 
      description: Registration is invoked when a mobile app is installed on a device and user details can be updated by the developer based on login. If the instance is already registered, existing instance entry shall be updated. Push notification token detail is masked and not displayed in response owing to security reasons.
      operationId: createMobileAppInstance
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: The mobile app identifier
        - name: appInstanceData
          in: body
          required: true
          schema:
            $ref: '#/definitions/AppInstanceRequest'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/AppInstanceResponse'
        'default':
          description: Other error with any status code and response body format.
  
    get:
      tags:
        - Mobile Apps
      security:
        - mobileapps:
          - nose.ma.r
        - appInstances:
          - nose.ai.r
      summary: Show all registered mobile app instances for a given mobile app. Push notification token detail is masked and not displayed in response owing to security reasons.
      operationId: queryMobileappInstances
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: The mobile app identifier
        - $ref: '#/parameters/page'
        - $ref: '#/parameters/size'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/PagedAppInstanceResponse'
        'default':
          description: Other error with any status code and response body format.

  /mobileApps/{id}/instances/{instanceId}:
    patch:
      tags:
        - Mobile Apps
      security:
        - appInstances:
          - nose.ai.w
      summary: Edit a specific mobile app instance registration. Push notification token detail is masked and not displayed in response owing to security reasons.
      operationId: patchMobileAppInstance
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: The mobile app identifier
        - name: instanceId
          in: path
          description: ID of mobile app instance to edit
          required: true
          type: string
        - name: mobileAppInstanceData
          in: body
          required: true
          schema:
            $ref: '#/definitions/AppInstancePatchRequest'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/AppInstanceResponse'
        'default':
          description: Other error with any status code and response body format.
          
    delete:
      tags:
        - Mobile Apps
      security:
        - appInstances:
          - nose.ai.w
      summary: Delete a specific mobile app instance registration.
      description: Deregistration of a mobile app involves deletion of the corresponding push notification token. Any pending notification jobs which depend on this configuration will be terminated, marked with a **failed** status and the notifications will not be dispatched to the mobile app instance.
      operationId: deleteMobileAppInstance
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: The mobile app identifier
        - name: instanceId
          in: path
          description: ID of app instance to delete
          required: true
          type: string
      responses:
        '204':
          description: No content
        'default':
          description: Other error with any status code and response body format.

definitions:
  AppInstancePatchRequest:
    type: object
    properties:
      deviceOS:
        type: string
        description: Device operating system
        example: iOS 10
      language:
        type: string
        description: Preffered ISO 639-1 Language code. Defaults to English if not specified.
        example: "de"
      pushNotificationToken:
        type: string
        description: Push notification identifier from Google or Apple.
        example: 7abcd558f29d0c1f048083e2134ad8ea4b3d87d8ae9c038b43c132706ff445f0
  
  AppInstanceObject:
    type: object
    properties:
      deviceOS:
        type: string
        description: Device operating system
        example: iOS 10
      language:
        type: string
        description: Preffered ISO 639-1 Language code. Defaults to English if not specified.
        example: "de"
      pushNotificationToken:
        type: string
        description: Masked value of the Push notification identifier from Google or Apple.
        example: XXXXXXXXXXXXXXXXXXXXXXXXX

  AppInstanceRequest:
    type: object
    allOf:
      - type: object
        properties:
          deviceModel:
            type: string
            example: iPhone X
            description: Attribute that will stored against a user, appId, registrationId. This can be displayed in UI and user can differentiate multiple installations of an app for the user in multiple mobile app instances.
      - $ref: '#/definitions/AppInstancePatchRequest'
    
  AppInstanceResponse:
    type: object
    allOf:
      - type: object
        properties:
          id:
            type: string
            example: '167e58934-5kk8-2389-5g90-ee4456betd1w'
      - $ref: '#/definitions/AppInstanceObject'
      
  AppInstanceResponseWithEmailAddress:
    type: object
    allOf:
      - $ref: '#/definitions/AppInstanceResponse'
      - type: object
        properties:
          userEmailAddress:
            type: string
            format: email
            example: 'joe.smith@siemens.com'

  PagedAppInstanceResponse:
    type: object
    properties:
      instances:
        type: array
        items:
          $ref: '#/definitions/AppInstanceResponseWithEmailAddress'
      page:
        $ref: '#/definitions/Page'
        
  AppRegistrationRequest:
    type: object
    properties:
      name:
        type: string
        description: App names must be made up of only uppercase and lowercase ASCII letters, numbers, underscores, hyphens, and periods, must be between 1 and 256 characters long, and must begin with a letter.
        example: 'Voith_Service_App'
      type:
        type: string
        enum: 
          - ios
          - android
        example: ios
        description: Describes the device platform. At least one device type should be specified. 
      android:
        type: object
        properties:
          fcmServerKey:
            type: string
            description: Firebase cloud messaging server key
      ios: 
        type: object
        properties:
          fcmServerKey:
            type: string
            description: Optional Firebase cloud messaging server key if FCM is to be used for sending notifications. If this key is not provided, an APNS notification will be sent using the certificate and private key provided.
          bundleId:
            type: string
            description: Bundle identifier of the iOS app
          apnsSslCertificate:
            type: string
            description: APNS SSL certificate content (.pem file format)
          apnsAppPrivateKey:
            type: string
            description: The private key associated with the APNS SSL certificate (.pem file format)
          production:
            type: boolean
            description: True for production environment, false for sandbox environment.
            default: false
  
  MobileAppObject:
    type: object
    properties:
      name:
        type: string
        description: App names must be made up of only uppercase and lowercase ASCII letters, numbers, underscores, hyphens, and periods, must be between 1 and 256 characters long, and must begin with a letter.
        example: 'Voith_Service_App'
      type:
        type: string
        enum: 
          - ios
          - android
        example: ios
        description: Describes the device platform. At least one device type should be specified. 
      android:
        type: object
        properties:
          fcmServerKey:
            type: string
            example: XXXXXXXXXXXXXXXXXXXXXXXXX
            description: Masked value of the Firebase cloud messaging server key
      ios: 
        type: object
        properties:
          fcmServerKey:
            type: string
            example: XXXXXXXXXXXXXXXXXXXXXXXXX
            description: Masked value of the Optional Firebase cloud messaging server key if FCM is to be used for sending notifications. If this key is not provided, an APNS notification will be sent using the certificate and private key provided.
          bundleId:
            type: string
            description: Bundle identifier of the iOS app
          apnsSslCertificate:
            type: string
            description: Masked value of the APNS SSL certificate content (.pem file format)
            example: XXXXXXXXXXXXXXXXXXXXXXXXX
          apnsAppPrivateKey:
            type: string
            description: Masked value of the private key associated with the APNS SSL certificate (.pem file format)
            example: XXXXXXXXXXXXXXXXXXXXXXXXX
          production:
            type: boolean
            description: True for production environment, false for sandbox environment.
            default: false

  AppRegistrationResponse:
    type: object
    allOf:
      - type: object
        properties:
          id:
            type: string
            example: '04f92378-7vvt-6720-5j10-kk9976befc1a'
          type:
            type: string
            enum: 
              - ios
              - android
            example: ios
            description: Describes the mobile platform.
      - $ref: '#/definitions/MobileAppObject'
  
  AppRegistrationUpdateRequest:
    type: object
    properties:
      name:
        type: string
        description: App names must be made up of only uppercase and lowercase ASCII letters, numbers, underscores, hyphens, and periods, must be between 1 and 256 characters long, and must begin with a letter.
        example: 'Voith_Service_App'
      android:
        type: object
        properties:
          fcmServerKey:
            type: string
            description: Firebase cloud messaging server key
      ios: 
        type: object
        properties:
          fcmServerKey:
            type: string
            description: Optional Firebase cloud messaging server key if FCM is to be used for sending notifications. If this key is not provided, an APNS notification will be sent using the certificate and private key provided.
          bundleId:
            type: string
            description: Bundle identifier of the iOS app
          apnsSslCertificate:
            type: string
            description: APNS SSL certificate content (.pem file format)
          apnsAppPrivateKey:
            type: string
            description: The private key associated with the APNS SSL certificate (.pem file format)
          production:
            type: boolean
            description: True for production environment, false for sandbox environment.
            default: false
    
  PagedAppRegistrationResponse:
    type: object
    properties:
      mobileApps:
        type: array
        items:
          $ref: '#/definitions/MobileAppObject'
      page:
        $ref: '#/definitions/Page'

  SendResponse:
    type: object
    properties:
      id:
        type: string
        example: '59f67823-5bhc-4780-8b23-ee8876mbtg9a'
      status:
        type: string
        enum:
          - queued
          - dispatched
          - failed
        example: queued
      startTime:
        description: The time at which the job started.
        type: string
        example: '2017-07-21T17:32:28.000Z'
        format: date-time
        pattern: YYYY-MM-DDThh:mm:ss.sssZ
  
  EmailJobResponse:
    type: object
    properties:
      id:
        type: string
        example: '59f67823-5bhc-4780-8b23-ee8876mbtg9a'
        description: The job id of the email job request. This can be used to get the status of the email job.

  SMSJobResponse:
    type: object
    properties:
      id:
        type: string
        example: '87e67823-5cha-5783-8b23-re8876m9ch4a'
        description: The job id of the SMS job request. This can be used to get the status of the sms job.

  Message:
    type: object
    properties:
      title:
        type: string
        description: The title of the notification. The content is a JSON object which contains a map of language codes to text for each language. The keys in the JSON should reflect valid ISO 639-1 language codes and English (en) should be mandatorily specified.
        example: '{ "en": "Siemens Mindsphere March 2019", "de": "Siemens MindSphere März 2019"}'
      text:
        type: string
        description: The content of the push notification. The content is a JSON object which contains a map of language codes to text for each language. Maximum size of a single text content should not exceed 2KB.
        example: '{ "en": "Hi there, Welcome to MindSphere!", "de": "Hallo, Willkommen bei MindSphere!"}'
        
  MulticastPushNotificationJobsRequest:
    type: object
    properties:
      mobileAppId:
        type: string
        description: The mobile app identifier.
        example: '65k88924-7ffc-1203-6h56-rr8834budg1w'
      recipients:
        type: object
        properties:
          appInstanceIds:
            description: Optional set of mobile app instance ids to send the notification to. Limit is 50 instance ids per request. 
            type: array
            items:
              type: string
              example: '91b55763-5eej-3489-8b78-hh5534weko7f'
          userEmailAddresses:
            description: Optional set of users (identified by email address) to send the notification to. Limit is 50 email addresses per request. 
            type: array
            items:
              type: string
              format: email
              example: joe.smith@siemens.com
      message:
        $ref: '#/definitions/Message'
  
  ScanDetail:
    type: object
    properties:
      filename:
        type: string
        example: "app.pdf"
      threat:
        description: Failed scan text.
        type: string
        example: "worm found"

  MulticastSMSNotificationJobRequest:
    type: object
    required:
      - recipients
      - fromApplication
      - message
    properties:
      message:
        type: string
        description: Body of the SMS message.
        minLength: 1
        maxLength: 1500
        example: Monthly machine data analysis completed. 
      recipients:
        type: array
        items:
          type: string
        minimum: 1
        maximum: 50
        description: List of valid mobile numbers including the country code.
        example: ['+411xxxxxxx9','+911xxxxxxx9']
      fromApplication: 
        type: string
        description: Source application which triggered the SMS Notification request. This name should match with the the registered application name with host tenant.

  MulticastEmailNotificationRequestMetadata:
    type: object
    required:
      - recipients
      - fromApplication
    properties:
      subject:
        type: string
        description: Subject to be displayed in the email notification.
      message:
        type: string
        description: Body of the email message.
      recipients:
        type: array
        items:
          type: string
        minimum: 1
        maximum: 50
      fromApplication: 
        type: string
        description: Source application which triggered the Email Notification request. This name should match with the the registered application name with host tenant.
      priority:
        type: string
        enum:
          - Low
          - Normal
          - High
        description: Optional priority to be requested for the email notification.
        default: Normal
  MulticastSMSNotificationJob:
    type: object
    properties:
      id:
        type: string
        description: Job ID of the triggered request
        example: '59f92744-7bbc-4540-8b78-ee9976befc1a'
      fromApplication:
        type: string
        description: Source application which triggered the SMS Notification request.
        example: 'MachineMonitor'
      status:
        type: string
        enum:
          - queued
          - dispatched
          - failed
        description: > 
          Provides status of the sms job request.
          <table>
            <tr>
              <th>Status</th>
              <th>Description</th>
            </tr>
            <tr>
              <td>queued</td>
              <td>SMS job request is received by the system.</td>
            </tr>
            <tr>
              <td>dispatched</td>
              <td>SMS job request is proccessed successfully. NOTE: The status "dispatched" does not guarantee successful delivery because of potential failures arising from downstream systems. </td>
            </tr>
            <tr>
              <td>failed</td>
              <td>Failed to dispatch the sms job, due to errors arising from downstream systems. No SMS is sent. The sender is requested to create a new sms job request.</td>
            </tr>
          </table>
        example: 'queued'
      startTime:
        type: string
        description: Time when the job was created.
        example: '2017-07-21T17:32:28.000Z'
  MulticastEmailNotificationJob:
    type: object
    properties:
      id:
        type: string
        description: Job ID of the triggered request
        example: '59f92744-7bbc-4540-8b78-ee9976befc1a'
      fromApplication:
        type: string
        description: Source application which triggered the Email Notification request.
        example: 'MachineMonitor'
      status:
        type: string
        enum:
          - queued
          - dispatched
          - dispatchedWithFailures
          - failed
        description: > 
          Provides status of the email job request.
          <table>
            <tr>
              <th>Status</th>
              <th>Description</th>
            </tr>
            <tr>
              <td>queued</td>
              <td>Email job request is received by the system. In case of attachements, email will be dispatched post scanning</td>
            </tr>
            <tr>
              <td>dispatched</td>
              <td>Email job request is proccessed successfully. NOTE: The status "dispatched" does not guarantee successful delivery because of potential failures arising from downstream systems. This status might change to "dispatchedWithFailures" in case the delivery was not successful to some of the recipeints.</td>
            </tr>
            <tr>
              <td>dispatchedWithFailures</td>
              <td>The system will set this status in two cases:
            <li>Attachments are found to be infected. In this case the email is sent without attachments.</li>
            <li>Delivery to some of the recipients failed.</li></td>
            </tr>
            <tr>
              <td>failed</td>
              <td>Failed to dispatch the email job, due to errors arising from downstream systems. No email is sent. The sender is requested to create a new email job request.</td>
            </tr>
          </table>
        example: 'queued'
      startTime:
        type: string
        description: Time when the job was created.
        example: '2017-07-21T17:32:28.000Z'
      maliciousAttachments:
        description: Details of the files that failed scanning.
        type: array
        items:
            $ref: '#/definitions/ScanDetail'
  DispatchStatusSMS:
    type: object
    properties:
      recipient:
        type: string
        example: '+411xxxxxxx9'
      status:
        description: Conveys the notification delivery status to individual recipient. The status "dispatched" does not guarantee successful delivery, because of potential failures that may arise from downstream systems. This status might change to "failed" in case the delivery was not successful.
        type: string
        enum: 
          - dispatched
          - failed
        example: 'failed'
  DispatchStatus:
    type: object
    properties:
      recipient:
        type: string
        example: 'plantengineer@mdspcustomer.com'
      status:
        description: Conveys the notification delivery status to individual recipient. The status "dispatched" does not guarantee successful delivery, because of potential failures that may arise from downstream systems. This status might change to "failed" in case the delivery was not successful.
        type: string
        enum: 
          - dispatched
          - failed
        example: 'failed'
  NotificationDispatchStatusSMS:
    type: object
    description: Shows the dispatch status of the notification per recipient.
    properties:
      dispatchStatus:
        type: array
        items:
          $ref: '#/definitions/DispatchStatusSMS'
      page:
        $ref: '#/definitions/Page' 
  NotificationDispatchStatus:
    type: object
    description: Shows the dispatch status of the notification per recipient.
    properties:
      dispatchStatus:
        type: array
        items:
          $ref: '#/definitions/DispatchStatus'
      page:
        $ref: '#/definitions/Page' 
  Errors:
    type: object
    description: Error response body model.
    properties:
      errors:
        type: array
        description: "Concrete error codes and messages are defined at operation error response descriptions in this API specification."
        items:
          type: object
          properties:
            code:
              type: string
              description: "Unique error code. Every code is bound to one (parametrized) message."
              format: "mdsp.core.notification.<suffix>"
              example: "mdsp.core.notification.exampleCode"
            logref:
              type: string
              description: "Logging correlation ID for debugging purposes."
              example: "0bff7e7a-cd25-4576-9908-4180ef086174"
            message:
              type: string
              description: "Human readable error message in English."
              example: "Example error message with parameter value 100"
            messageParameters:
              type: array
              description: |
                In case an error message is parametrized, the parameter names and values are returned for, e.g., localization purposes. The parametrized error messages are defined at the operation error response descriptions in this API specification. Parameters are denoted by named placeholders '{\<parameter name\>}' in the  message specifications. At runtime, returned message placeholders are substituted by actual parameter values.
              items:
                type: object
                description: "Message parameter"
                properties:
                  name:
                    type: string
                    description: "Name of message parameter as specified in parametrized error message."
                  value:
                    type: string
                    description: "Value of message parameter as substituted in returned error message."
              example:
                - { "name": "exampleParameterName", "value": "100" }

  Page:
    type: object
    properties:
      size:
        type: integer
      totalElements:
        type: integer
      totalPages:
        type: integer
      number:
        type: integer

parameters:
  page:
    name: page
    in: query
    type: integer
    description: Specifies the requested page index
  size:
    name: size
    in: query
    type: integer
    description: Specifies the number of elements in a page. Maximum size value allowed is 50.
