Angebotserstellung mit mehreren Versionen

Standardmäßig hat ein Job ab dem Zeitpunkt seiner Erstellung eine Version, und diese Version befindet sich im ausgewählten Status. Um auf die Jobversionen zuzugreifen, können Aufrufer eine GET-Anforderung an die /job/v1/jobs/{jobId}/versions-Sammlung senden.

Der folgende Codeblock zeigt die Antwort-Nutzdaten einer GET-Anforderung an die /versions-Sammlung eines neu erstellten Jobs, der eine Version enthält:

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "id": "pc:401",
                "name": "Version #1",
                "number": 1,
                "selected": true,
                "status": {
                    "code": "Draft",
                    "name": "Draft"
                }
            },
            . . .
        }
    ],
    . . .
}

Das Feld attributes enthält die folgenden Eigenschaften:

• id : Den ID-Wert der Version. Die erste Version eines Jobs hat denselben ID-Wert wie der Job selbst.
• name : Eine von einem Benutzer lesbare Zeichenfolge, mit der die Jobversion identifiziert werden kann.
• number : Die 1-basierte Indexnummer der Version in der versions-Sammlung. Die Eigenschaft ist ein syntaktischer Zucker, der ein Handle bereitstellt, das Anwendungen beim Iterieren über ein Versionen-Array verwenden können.
• selected : Ein Boolescher Wert, der den ausgewählten Status der Version angibt.
• status : Ein Typenschlüsselwert, der den Jobstatus angibt. Jobs haben ab dem Zeitpunkt der Erstellung den Status „Entwurf“ bzw. den Status „Angebot erstellt“, sobald ein Angebot erstellt wurde.

Mit Ausnahme von name sind diese Eigenschaften schreibgeschützte Werte.

Ein Aufrufer kann eine neue Version eines Jobs erstellen, indem er eine POST-Anforderung an den Endpunkt /job/v1/jobs/{jobId}/versions sendet. Die Anforderungs-Nutzdaten müssen mindestens Daten- und Attributeigenschaften enthalten, und letztere können leer sein:

{
  "data": {
    "attributes": { }
  }
}

Optional kann der Aufrufer einen Namen für die Version angeben:

{
  "data": {
    "attributes": {
        "name": "My new version"
     }
  }
}

Bei der Erstellung hat die neue Jobversion den Status „Entwurf“, sie ist nicht ausgewählt und die Versionsnummer wird um eins erhöht. Der ID-Wert ist versionsspezifisch.

{
    "data": {
        "attributes": {
            "id": "pc:402",
            "name": "My new version",
            "number": 2,
            "selected": false,
            "status": {
                "code": "Draft",
                "name": "Draft"
            }
        },
        . . .
    }
}

Standardmäßig sind der anfängliche Job und die erste Version identisch, haben denselben ID-Wert, und diese Version ist ausgewählt. Nachfolgende Versionen sind standardmäßig nicht ausgewählt.

Ein Aufrufer kann eine Jobversion auswählen, indem er eine POST-Anforderung an den /job/v1/jobs/{jobId}/change-version-Endpunkt sendet. Die Anforderungs-Nutzdaten müssen die auszuwählende Version angeben:

{
  "data": {
    "attributes": {
      "selectedVersion": {
        "id": "pc:402"
      }
    }
  }
}

In den obigen Nutzdaten wird der Wert selectedVersion.id auf den ID-Wert der Jobversion gesetzt, die im vorherigen Abschnitt erstellt wurde. Diese Jobversion wird nun ausgewählt, und alle anderen Jobversionen befinden sich in einem nicht ausgewählten Status.

Eine ausgewählte Jobversion im Status „Entwurf“ kann über die Endpunkte /job/v1/jobs/{selectedJobId} geändert oder ein Angebot dafür erstellt werden.

Alternativ kann ein Aufrufer eine nicht ausgewählte Jobversion im Status „Entwurf“ ändern oder ein Angebot dafür erstellen, indem er den Abfrageparameter jobVersion auf die Anforderung anwendet. Diese Aufrufe weisen die folgenden Muster auf:

• /job/v1/jobs/{selectedJobId}?jobVersion={unselectedJobId}
• /job/v1/jobs/{selectedJobId}/{businessAction}?jobVersion={unselectedJobId}

In der Regel wird jede Version geändert, bis sie als abgeschlossen betrachtet wird, und anschließend ein Angebot erstellt. Die angebotenen Versionen können dann zum Nebeneinander-Vergleich angeboten werden. Um eine angebotene Version weiter zu ändern, kann ein Aufrufer die Geschäftsaktion /make-draft auf diese Version anwenden, die Änderung vornehmen und dann ein neues Angebot erstellen.