In questa pagina
> risorse > documentazione > api > Riferimento API: Simulazioni

Riferimento API: Simulazioni

Le simulazioni consentono di eseguire scenari what-if sui modelli di processo. È possibile configurare i tempi di elaborazione, l’allocazione delle risorse e i tassi di arrivo per prevedere il comportamento del processo.

Elencare le simulazioni di un processo

Endpoint: GET /v1/tenant/{tenantId}/processes/{processId}/simulations

Autenticazione: Chiave API con ambito tenant · ambito read

Parametri:

Nome Tipo Posizione Obbligatorio Descrizione
tenantId string percorso Sì Formato: uuid
processId string percorso Sì Formato: uuid
limit integer query No Numero massimo di elementi da restituire
offset integer query No Numero di elementi da ignorare

Risposta (200):

Elenco delle simulazioni

[
	{
		"id": "00000000-0000-0000-0000-000000000000",
		"displayName": "string",
		"datasetName": "string",
		"startTime": "2024-03-15T16:30:00Z",
		"endTime": "2024-03-15T16:30:00Z",
		"useWarmUp": true
	}
]

Errori:

  • 400 Richiesta non valida: ad esempio, un’espressione di filtro non valida, un processo senza modello, un tipo di caricamento non supportato o un campo obbligatorio mancante
  • 401 Chiave API mancante, non valida, disabilitata o scaduta
  • 404 Risorsa non trovata

Creare una simulazione (idempotente quando viene fornito un ID)

Endpoint: POST /v1/tenant/{tenantId}/processes/{processId}/simulations

Autenticazione: Chiave API con ambito tenant · ambito write

Parametri:

Nome Tipo Posizione Obbligatorio Descrizione
tenantId string percorso Sì Formato: uuid
processId string percorso Sì Formato: uuid

Corpo della richiesta:

{
	"id": "00000000-0000-0000-0000-000000000000",
	"displayName": "string",
	"datasetName": "string",
	"startTime": "2024-03-15T16:30:00Z",
	"endTime": "2024-03-15T16:30:00Z",
	"useWarmUp": true
}
Campo Tipo Obbligatorio Descrizione
id string No ID facoltativo per i nuovi tentativi idempotenti (deve essere un UUID)
Formato: uuid
displayName string No Nome della simulazione
Valore predefinito: New Simulation
datasetName string No Nome del dataset su cui viene eseguita la simulazione
startTime string No Ora di inizio della simulazione
Formato: date-time
endTime string No Ora di fine della simulazione
Formato: date-time
useWarmUp boolean No Indica se ignorare il periodo di transitorio
Valore predefinito: false

Risposta (201):

Simulazione creata

{
	"simulation": {
		"id": "00000000-0000-0000-0000-000000000000",
		"displayName": "string"
	},
	"message": "string"
}
Campo Tipo Obbligatorio Descrizione
simulation object Sì
message string Sì

Errori:

  • 400 Richiesta non valida: ad esempio, un’espressione di filtro non valida, un processo senza modello, un tipo di caricamento non supportato o un campo obbligatorio mancante
  • 401 Chiave API mancante, non valida, disabilitata o scaduta
  • 404 Risorsa non trovata
  • 409 La richiesta è in conflitto con lo stato attuale, ad esempio per un vincolo sulla postazione o per un ID già utilizzato

Ottenere una simulazione con le impostazioni degli elementi, gli attributi e le risorse

Endpoint: GET /v1/tenant/{tenantId}/processes/{processId}/simulations/{simulationId}

Autenticazione: Chiave API con ambito tenant · ambito read

Parametri:

Nome Tipo Posizione Obbligatorio Descrizione
tenantId string percorso Sì Formato: uuid
processId string percorso Sì Formato: uuid
simulationId string percorso Sì Formato: uuid

Risposta (200):

Dettagli della simulazione

{
	"simulation": {
		"id": "00000000-0000-0000-0000-000000000000",
		"displayName": "string",
		"datasetName": "string",
		"startTime": "2024-03-15T16:30:00Z",
		"endTime": "2024-03-15T16:30:00Z",
		"useWarmUp": true
	},
	"elementSettings": [
		{
			"simulationId": "00000000-0000-0000-0000-000000000000",
			"modelElementId": "00000000-0000-0000-0000-000000000000",
			"settings": {
				"processingTimeDistribution": [
					{
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"distribution": {
							"type": "Fixed",
							"value": 0
						},
						"timeUnit": "seconds",
						"rateUnit": "perTimeSlot"
					}
				],
				"processingTimeUnit": "seconds",
				"updateAttributeRules": [
					{
						"id": "string",
						"attributeId": "00000000-0000-0000-0000-000000000000",
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"newValue": "string",
						"isEnabled": true
					}
				],
				"requiredResources": [
					{
						"resourceId": "00000000-0000-0000-0000-000000000000",
						"amount": 0
					}
				],
				"caseStartsDistribution": [
					{
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"distribution": {
							"type": "Fixed",
							"value": 0
						},
						"timeUnit": "seconds",
						"rateUnit": "perTimeSlot"
					}
				],
				"caseStartsTimeUnit": "perTimeSlot",
				"capacityInterval": "perHour",
				"skipChanceDistribution": [
					{
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"distribution": {
							"type": "Fixed",
							"value": 0
						},
						"timeUnit": "seconds",
						"rateUnit": "perTimeSlot"
					}
				],
				"queueStrategy": "fifo",
				"chanceToTakeDistribution": [
					{
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"distribution": {
							"type": "Fixed",
							"value": 0
						},
						"timeUnit": "seconds",
						"rateUnit": "perTimeSlot"
					}
				]
			}
		}
	],
	"attributes": [
		{
			"id": "00000000-0000-0000-0000-000000000000",
			"simulationId": "00000000-0000-0000-0000-000000000000",
			"displayName": "string",
			"valueDistribution": {
				"type": "Number",
				"numberDistributions": [
					{
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"distribution": {
							"type": "Fixed",
							"value": 0
						},
						"timeUnit": "seconds",
						"rateUnit": "perTimeSlot",
						"id": "string",
						"isEnabled": true,
						"isDefault": true
					}
				],
				"textDistributions": [
					{
						"id": "string",
						"timeslot": {
							"periodicity": "Always"
						},
						"isEnabled": true,
						"isDefault": true,
						"mode": "list",
						"textValues": [
							{
								"id": "string",
								"value": "string",
								"chance": 0
							}
						]
					}
				]
			},
			"simulationAttributeType": "string"
		}
	],
	"resources": [
		{
			"id": "00000000-0000-0000-0000-000000000000",
			"simulationId": "00000000-0000-0000-0000-000000000000",
			"displayName": "string",
			"levelDistribution": [
				{
					"timeslot": {
						"periodicity": "Always"
					},
					"conditions": [
						{
							"type": "Values",
							"attribute": "string",
							"values": [
								"string"
							]
						}
					],
					"distribution": {
						"type": "Fixed",
						"value": 0
					},
					"timeUnit": "seconds",
					"rateUnit": "perTimeSlot"
				}
			],
			"attributeId": "00000000-0000-0000-0000-000000000000"
		}
	]
}
Campo Tipo Obbligatorio Descrizione
simulation object Sì Intestazione della simulazione
elementSettings object[] Sì Impostazioni della simulazione per elemento
attributes object[] Sì Attributi simulati
resources object[] Sì Pool di risorse

Errori:

  • 400 Richiesta non valida: ad esempio, un’espressione di filtro non valida, un processo senza modello, un tipo di caricamento non supportato o un campo obbligatorio mancante
  • 401 Chiave API mancante, non valida, disabilitata o scaduta
  • 404 Risorsa non trovata

Aggiornare una simulazione (campi e/o impostazioni degli elementi)

Endpoint: PUT /v1/tenant/{tenantId}/processes/{processId}/simulations/{simulationId}

Autenticazione: Chiave API con ambito tenant · ambito write

Parametri:

Nome Tipo Posizione Obbligatorio Descrizione
tenantId string percorso Sì Formato: uuid
processId string percorso Sì Formato: uuid
simulationId string percorso Sì Formato: uuid

Corpo della richiesta:

{
	"displayName": "string",
	"datasetName": "string",
	"startTime": "2024-03-15T16:30:00Z",
	"endTime": "2024-03-15T16:30:00Z",
	"useWarmUp": true,
	"elementSettings": [
		{
			"modelElementId": "00000000-0000-0000-0000-000000000000",
			"settings": {
				"caseStartsDistribution": [
					{
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"distribution": {
							"type": "Fixed",
							"value": 0
						},
						"timeUnit": "seconds",
						"rateUnit": "perTimeSlot"
					}
				],
				"processingTimeDistribution": [
					{
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"distribution": {
							"type": "Fixed",
							"value": 0
						},
						"timeUnit": "seconds",
						"rateUnit": "perTimeSlot"
					}
				]
			}
		}
	]
}
Campo Tipo Obbligatorio Descrizione
displayName string No Nome della simulazione
datasetName string No Nome del dataset su cui viene eseguita la simulazione
startTime string No Ora di inizio della simulazione
Formato: date-time
endTime string No Ora di fine della simulazione
Formato: date-time
useWarmUp boolean No Indica se ignorare il periodo di transitorio
elementSettings object[] No Sostituzioni delle impostazioni per elemento

Risposta (200):

Simulazione aggiornata

{
	"message": "string"
}
Campo Tipo Obbligatorio Descrizione
message string Sì

Errori:

  • 400 Richiesta non valida: ad esempio, un’espressione di filtro non valida, un processo senza modello, un tipo di caricamento non supportato o un campo obbligatorio mancante
  • 401 Chiave API mancante, non valida, disabilitata o scaduta
  • 404 Risorsa non trovata

Eliminare definitivamente una simulazione

Endpoint: DELETE /v1/tenant/{tenantId}/processes/{processId}/simulations/{simulationId}

Autenticazione: Chiave API con ambito tenant · write ambito

Parametri:

Nome Tipo Posizione Obbligatorio Descrizione
tenantId string path Sì Formato: uuid
processId string path Sì Formato: uuid
simulationId string path Sì Formato: uuid

Risposta (200):

Simulazione eliminata

{
	"message": "string"
}
Campo Tipo Obbligatorio Descrizione
message string Sì

Errori:

  • 400 Richiesta non valida: ad esempio, un’espressione di filtro non valida, un processo senza modello, un tipo di caricamento non supportato o un campo obbligatorio mancante
  • 401 Chiave API mancante, non valida, disabilitata o scaduta
  • 404 Risorsa non trovata

Questi endpoint utilizzano l’AI per generare automaticamente le impostazioni della simulazione in base al modello di processo.

Generare le impostazioni della simulazione tramite AI (asincrono; interrogare l’endpoint dello stato)

Endpoint: POST /v1/tenant/{tenantId}/processes/{processId}/simulations/{simulationId}/generate-settings

Autenticazione: Chiave API con ambito tenant · write ambito · limite di frequenza 2 richieste/s (burst 4)

Parametri:

Nome Tipo Posizione Obbligatorio Descrizione
tenantId string path Sì Formato: uuid
processId string path Sì Formato: uuid
simulationId string path Sì Formato: uuid

Corpo della richiesta:

{
	"processDescription": "string",
	"additionalContext": "string"
}
Campo Tipo Obbligatorio Descrizione
processDescription string No
additionalContext string No

Risposta (200):

Generazione avviata / risultato

{
	"message": "string"
}
Campo Tipo Obbligatorio Descrizione
message string Sì

Errori:

  • 400 Richiesta non valida: ad esempio, un’espressione di filtro non valida, un processo senza modello, un tipo di caricamento non supportato o un campo obbligatorio mancante
  • 401 Chiave API mancante, non valida, disabilitata o scaduta
  • 404 Risorsa non trovata

Interrogare lo stato della generazione delle impostazioni della simulazione

Endpoint: GET /v1/tenant/{tenantId}/processes/{processId}/simulations/{simulationId}/generate-settings/status

Autenticazione: Chiave API con ambito tenant · write ambito

Parametri:

Nome Tipo Posizione Obbligatorio Descrizione
tenantId string path Sì Formato: uuid
processId string path Sì Formato: uuid
simulationId string path Sì Formato: uuid

Risposta (200):

Stato della generazione

{
	"message": "string"
}
Campo Tipo Obbligatorio Descrizione
message string Sì

Errori:

  • 400 Richiesta non valida: ad esempio, un’espressione di filtro non valida, un processo senza modello, un tipo di caricamento non supportato o un campo obbligatorio mancante
  • 401 Chiave API mancante, non valida, disabilitata o scaduta
  • 404 Risorsa non trovata

Avviare un’esecuzione di simulazione (asincrona; i risultati vengono inseriti nelle tabelle dati del processo)

Endpoint: POST /v1/tenant/{tenantId}/processes/{processId}/simulations/{simulationId}/run

Autenticazione: Chiave API con ambito tenant · write ambito · limite di frequenza 5 richieste/s (burst 10)

Parametri:

Nome Tipo Posizione Obbligatorio Descrizione
tenantId string path Sì Formato: uuid
processId string path Sì Formato: uuid
simulationId string path Sì Formato: uuid

Risposta (200):

Simulazione avviata

{
	"message": "string"
}
Campo Tipo Obbligatorio Descrizione
message string Sì

Errori:

  • 400 Richiesta non valida: ad esempio, un’espressione di filtro non valida, un processo senza modello, un tipo di caricamento non supportato o un campo obbligatorio mancante
  • 401 Chiave API mancante, non valida, disabilitata o scaduta
  • 404 Risorsa non trovata

Ottenere lo stato dell’ultima esecuzione di simulazione (derivato dalla tabella dati di output)

Endpoint: GET /v1/tenant/{tenantId}/processes/{processId}/simulations/{simulationId}/run/status

Autenticazione: Chiave API con ambito tenant · read ambito

Parametri:

Nome Tipo Posizione Obbligatorio Descrizione
tenantId string path Sì Formato: uuid
processId string path Sì Formato: uuid
simulationId string path Sì Formato: uuid

Risposta (200):

Stato dell’esecuzione

{
	"state": "notStarted",
	"startedAt": "2024-03-15T16:30:00Z",
	"completedAt": "2024-03-15T16:30:00Z",
	"step": "string",
	"casesSimulated": 0,
	"targetCases": 0,
	"eventsGenerated": 0,
	"errorMessage": "string",
	"simulationId": "00000000-0000-0000-0000-000000000000"
}
Campo Tipo Obbligatorio Descrizione
state notStarted | running | processing | ready | error Sì Valori consentiti: notStarted, running, processing, ready, error
startedAt string No Formato: date-time
completedAt string No Formato: date-time
step string No
casesSimulated number No
targetCases number No
eventsGenerated number No
errorMessage string No
simulationId string Sì Formato: uuid

Errori:

  • 400 Richiesta non valida: ad esempio, un’espressione di filtro non valida, un processo senza modello, un tipo di caricamento non supportato o un campo obbligatorio mancante
  • 401 Chiave API mancante, non valida, disabilitata o scaduta
  • 404 Risorsa non trovata

Documentazione correlata