Riferimento API: simulazioni

Le simulazioni consentono di eseguire scenari ipotetici 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 associata al tenant · ambito read

Parametri:

Nome	Tipo	Posizione	Obbligatorio	Descrizione
tenantId	string	path	Sì	Formato: uuid
processId	string	path	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, espressione di filtro non valida, processo senza modello, tipo di caricamento non supportato o campo obbligatorio mancante
• 401 Chiave API mancante, non valida, disabilitata o scaduta
• 404 Risorsa non trovata

Creare una simulazione (operazione idempotente se viene fornito un ID)

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

Autenticazione: Chiave API associata al tenant · ambito write

Parametri:

Nome	Tipo	Posizione	Obbligatorio	Descrizione
tenantId	string	path	Sì	Formato: uuid
processId	string	path	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 Predefinito: New Simulation
datasetName	string	No	Nome del set di dati 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 escludere il periodo di avvio 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, espressione di filtro non valida, processo senza modello, tipo di caricamento non supportato o 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 limite di postazioni o un ID già utilizzato)

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

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

Autenticazione: Chiave API associata al tenant · ambito read

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):

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 ciascun elemento
attributes	object[]	Sì	Attributi simulati
resources	object[]	Sì	Pool di risorse

Errori:

• 400 Richiesta non valida: ad esempio, espressione di filtro non valida, processo senza modello, tipo di caricamento non supportato o 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 associata al tenant · ambito write

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:

{
	"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 set di dati 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 escludere il periodo di avvio
elementSettings	object[]	No	Sostituzioni delle impostazioni per ciascun elemento

Risposta (200):

Simulazione aggiornata

{
	"message": "string"
}

Campo	Tipo	Obbligatorio	Descrizione
message	string	Sì

Errori:

• 400 Richiesta non valida: ad esempio, espressione di filtro non valida, processo senza modello, tipo di caricamento non supportato o 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 associata al tenant · ambito write

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, espressione di filtro non valida, processo senza modello, tipo di caricamento non supportato o 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 con l’AI (in modo asincrono; interrogare l’endpoint di stato)

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

Autenticazione: Chiave API associata al tenant · ambito write · limite di richieste: 2 richieste/s (picco 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, espressione di filtro non valida, processo senza modello, tipo di caricamento non supportato o campo obbligatorio mancante
• 401 Chiave API mancante, non valida, disabilitata o scaduta
• 404 Risorsa non trovata

Verificare lo stato della generazione delle impostazioni della simulazione

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

Autenticazione: Chiave API associata al tenant · ambito write

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, espressione di filtro non valida, processo senza modello, tipo di caricamento non supportato o campo obbligatorio mancante
• 401 Chiave API mancante, non valida, disabilitata o scaduta
• 404 Risorsa non trovata

Avviare una simulazione (in modo asincrono; i risultati vengono salvati nelle tabelle dati del processo)

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

Autenticazione: Chiave API associata al tenant · ambito write · limite di richieste: 5 richieste/s (picco 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, espressione di filtro non valida, processo senza modello, tipo di caricamento non supportato o campo obbligatorio mancante
• 401 Chiave API mancante, non valida, disabilitata o scaduta
• 404 Risorsa non trovata

Recuperare lo stato dell’ultima simulazione (ricavato dalla tabella dati di output)

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

Autenticazione: Chiave API associata al tenant · ambito read

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, espressione di filtro non valida, processo senza modello, tipo di caricamento non supportato o campo obbligatorio mancante
• 401 Chiave API mancante, non valida, disabilitata o scaduta
• 404 Risorsa non trovata