AcumatiCares
Dans le billet d'aujourd'hui, je vais vous présenter les API d'Acumatica Cloud ERP qui permettent l'intégration avec des systèmes et des applications externes. Grâce aux services web, les applications externes peuvent obtenir des enregistrements de données d'Acumatica, traiter ces enregistrements, les sauvegarder, en créer de nouveaux ou les mettre à jour. Aujourd'hui, nous mettons à la disposition des développeurs et des intégrateurs de systèmes des API basées sur des écrans et des contrats, qui reposent sur des interfaces SOAP. Dans un avenir proche, nous déploierons nos API contractuelles compatibles REST, qui permettront aux développeurs d'utiliser des interfaces REST. J'approfondirai la question dans un prochain billet de blog, en donnant plus de détails sur notre mise en œuvre de REST. La figure 1 ci-dessous représente graphiquement ces interfaces API entre notre base de produits ERP (Enterprise Resource Planning) et les applications tierces.
API de services Web basés sur l'écran
Nos API basées sur l'écran sont conçues pour fonctionner avec tous nos formulaires Acumatica ERP en utilisant directement les champs et les actions disponibles sur ces formulaires. Par exemple, dans le formulaire ci-dessous, chaque élément - une zone de texte, une zone combo ou une colonne de tableau - est associé à une classe d'API de services web particulière et est disponible par le biais d'une propriété correspondante de cette classe. La propriété porte un nom similaire à celui de la case correspondante du formulaire.
Après vous être connecté à Acumatica en utilisant l'API, vous pouvez accéder aux données des formulaires disponibles par le biais d'un simple service web. Nous fournissons une classe d'écran des méthodes API pour travailler avec tous les formulaires Acumatica ERP disponibles via le service. Vous pouvez savoir à quel formulaire une méthode accède grâce au préfixe dans le nom de la méthode, qui est l'ID du formulaire. Par exemple, la méthode Export() que vous utilisez pour exporter les données des articles en stock du formulaire d'inventaire IN202500 est IN202500Export().
Exemple de code à l'écran : Récupération d'une liste d'articles en stock
Examinons un exemple de code dans lequel nous récupérons une liste d'articles en stock à l'aide de l'API basée sur l'écran.
//Retrieving the list of stock items from inventory
public static void ExportStockItems()
{
using
{
//Connect to the web service and log in to Acumatica ERP
Screen context = WebServiceConnector.InitializeWebService()
}
{
try
{
IN202500Content stockItemsSchema = context.IN202500GetSchema();
var commands = new Command[]
{
stockItemsSchema.StockItemSummary.ServiceCommands.EveryInventoryID,
stockItemsSchema.StockItemSummary.InventoryID,
stockItemsSchema.StockItemSummary.Description,
stockItemsSchema.GeneralSettingsItemDefaults.ItemClass,
stockItemsSchema.GeneralSettingsUnitOfMeasureBaseUnit.BaseUnit,
new Field
{
ObjectName =
stockItemsSchema.StockItemSummary.InventoryID.ObjectName,
FieldName = “LastModifiedDateTime”
}
};
}
finally
{
context.Logout();
}
}
}
Notez que la ligne du code ci-dessus, IN202500Content stockItemsSchema = context.IN202500GetSchema() ; fait référence à l'écran Inventaire (IN2025000) et à son contenu et est donc liée à un écran spécifique qui est l'écran ou le formulaire que nous avons montré précédemment dans la figure 2.
Les API basées sur les écrans sont uniques à Acumatica - elles offrent une valeur considérable en termes d'un ensemble de capacités riches et d'une grande flexibilité. Cependant, elles sont liées à l'écran et tout changement dans l'écran tend à modifier l'API elle-même. Par exemple, le déplacement d'un contrôle d'un groupe à un autre - l'ajout d'une petite bordure - peut vous obliger à recompiler votre code afin de vous assurer que tout fonctionne correctement. Tout ce qui peut être fait au niveau de l'écran dans Acumatica peut être fait avec l'API basée sur l'écran. Cela signifie que vous pouvez automatiser presque n'importe quelle activité ou tâche. Jetons maintenant un coup d'œil à nos API basées sur les contrats.
API de services Web basés sur des contrats
Ces API ont été introduites dans Acumatica 5.3 en février de cette année et sont relativement nouvelles. Les API basées sur des contrats fonctionnent avec des objets de logique d'entreprise qui ne sont pas liés à l'écran en tant que tel, ainsi qu'avec leurs propriétés et méthodes. Les API basées sur des contrats sont construites sur un modèle d'objet fourni par l'API des services web. Elles ne changent pas en fonction de la personnalisation du système, de la localisation ou de toute autre modification apportée à Acumatica Enterprise Resource Planning (ERP), comme les formulaires.
Par exemple, supposons que vous ayez écrit un code utilisant le champ ItemClass, qui accède au même élément ID ItemClass que nous avons trouvé dans le formulaire d'inventaire IN2025000 dans notre exemple d'API basée sur l'écran. Si vous modifiez le nom de l'élément ID ItemClass dans votre projet de personnalisation, votre code reste entièrement fonctionnel et ne nécessite pas de recompilation ni de modifications supplémentaires. Vous pouvez accéder à l'élément ItemClass ID sur le formulaire via le même champ ItemClassID.
Exemple de code basé sur un contrat simple : Récupération d'une liste d'articles en stock
Comme dans l'exemple à l'écran de la section précédente, nous montrons ici comment il est facile de récupérer des articles en stock dans l'inventaire. Notez les différences entre les codes. Ici, notre code ne fait pas référence à un écran pour récupérer les articles et est très simple et direct.
//Retrieving the list of stock items from inventory
public static void ExportStockItems()
{
using (DefaultSoapClient soapClient = new DefaultSoapClient())
{
//Log in to Acumatica ERP
WebServiceConnector.InitializeWebService(soapClient);
try
{
//Get the list of stock items
Entity[] stockItems =
soapClient.GetList(stockItemsToBeFound, False);
}
finally
{
//Log out from Acumatica ERP
soapClient.Logout();
}
}
}
Pour tout nouveau projet de développement de nos partenaires actuels ou pour votre premier projet de développement en tant que nouveau partenaire, il convient d'utiliser les API basées sur les contrats. Cependant, certaines fonctionnalités du système ne sont pas encore exposées. Il vous arrivera donc d'utiliser encore certaines des API basées sur l'écran. L'utilisation des API contractuelles les plus récentes offre une plus grande stabilité : vous ne risquez pas de rencontrer des problèmes liés à des modifications de votre application ou à des changements que nous pourrions apporter de notre côté et qui pourraient affecter la fonctionnalité de vos applications sans qu'il soit nécessaire de les recompiler. Il va sans dire qu'il est important de toujours tester vos applications lorsqu'une nouvelle version du produit est publiée, et pas seulement au cours de votre cycle de développement.
Résumé
Les API basées sur l'écran sont uniques à Acumatica - considérez-les comme une sorte d'interface de script pour obtenir des données en entrée et en sortie de notre plateforme système. Plus important encore, n'oubliez pas qu'elles sont liées à l'écran. Chaque écran Acumatica a des champs, des groupes et des conteneurs... et ainsi de suite. Chaque modification de l'écran tend à modifier l'API. Par exemple, déplacer un contrôle d'un groupe à un autre - apporter de petites modifications au formulaire ou au code peut faire en sorte que l'application ne fonctionne pas comme prévu - recompilez votre code pour vous en assurer. Grâce à ces API, vous bénéficiez d'une très grande souplesse et d'une grande richesse fonctionnelle. Tout ce qui peut être fait au niveau de l'écran peut également être fait avec l'API, ce qui vous donne la possibilité d'automatiser presque tout dans le système.
Avec la publication des API basées sur des contrats, nous exposons nos modèles de données - par exemple CRUD, détails et méthodes simples - qui sont strictement définis. Vous pouvez créer une entité, la mettre à jour, la lire par critères, par identifiants clés, etc. Nous avons exposé et défini notre modèle de données, dont le développeur peut tirer parti sans se soucier des modifications à l'écran qui peuvent entrer en conflit et casser l'application. Nous encapsulons les changements et cachons la complexité au développeur. Nous avons essentiellement conclu un "contrat" avec les développeurs, qui leur promet que les modifications sous-jacentes que nous apportons ne casseront pas leur code.
En écoutant les commentaires de nos clients et partenaires, nous avons lancé nos API basées sur les contrats en février dernier. Bientôt, nous lancerons nos API contractuelles compatibles avec REST, qui présentent un certain nombre d'avantages supplémentaires très appréciés des développeurs. Nous fournirons plus de détails dans les prochains articles de ce blog. Nous publierons très prochainement une discussion vidéo sur nos API, y compris un premier aperçu de la prise en charge REST.
Nous réitérons un message important à nos lecteurs : toutes les nouvelles intégrations et tous les nouveaux projets de développement doivent être réalisés à l'aide des API contractuelles. Bien que nous investissions nos efforts dans les API basées sur les contrats, les API basées sur les écrans continueront d'être maintenues dans un avenir prévisible. Nous nous attendons à ce que le code de nos partenaires actuels migre au fil du temps pour profiter des avantages de nos API contractuelles.
Pour plus de détails, téléchargez notre Guide du développeur . Si vous avez des questions, visitez notre forum de développeurs sur StackOverflow et posez vos questions.
