Xrm.Utility(클라이언트 쪽 참조)

  • 아티클

 

게시 날짜: 2017년 1월

적용 대상: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Xrm.Utility 개체는 현재 페이지와 직접 관련이 없는 유용한 함수를 위한 컨테이너를 제공합니다.

이러한 함수는 스크립팅을 지원하는 모든 응용 프로그램 페이지에서 사용할 수 있습니다. 양식 스크립트 또는 리본 메뉴 명령에서 사용할 수 있습니다.HTML 웹 리소스의 경우 ClientGlobalContext.js.aspx 페이지를 포함할 때 사용할 수 있습니다. 자세한 내용은 GetGlobalContext 함수 및 ClientGlobalContext.js.aspx(클라이언트 쪽 참조)을 참조하십시오.

Functions

  • 대화
    alertDialog 및 confirmDialog를 사용하여 메시지를 사용자에게 표시하고 해당 응답을 기반으로 실행할 코드를 설정합니다. 이러한 함수는 window.alert 및 window.confirm 메서드 자리에서 Dynamics 365 모바일 클라이언트(휴대폰 및 태블릿)와 함께 사용해야 합니다.

  • 기본 장치 기능(Dynamics 365 모바일 클라이언트)
    getBarcodeValue 및 getCurrentPosition를 사용하여 바코드 값을 검색하거나 장치의 현재 위치를 검색하는 데 모바일 장치의 기본 장치 기능을 사용합니다.

  • isActivityType
    엔터티가 활동 엔터티인지 확인합니다.

  • openEntityForm
    엔터티 양식을 엽니다.

  • openQuickCreate
    Microsoft Dynamics CRM Online 2015 업데이트 1 이상인 경우 이 기능을 사용하여 새로운 빨리 만들기 양식을 엽니다. 이 기능을 사용하여 특성 매핑 사용 또는 특정 특성에 대한 기본값을 설정합니다. 레코드를 저장하는 경우 만든 레코드에 대한 참조를 캡처할 수 있습니다.

  • openWebResource
    HTML 웹 리소스를 엽니다.

대화

alertDialog 및 confirmDialog의 두 가지 대화 상자 유형이 있습니다.Dynamics 365 모바일 클라이언트(휴대폰과 태블릿)에서 작동하는 스크립트와 사용할 수 있도록 포함되어 있습니다.Dynamics 365 모바일 클라이언트는 window.alert 및 window.confirm 등 코드 흐름을 차단하는 JavaScript 함수의 사용을 허용하지 않습니다. 메시지를 사용자에게 표시해야 하는 경우 해당 메서드 대신 이러한 메서드를 사용합니다. 주요 차이점은 이러한 메서드는 사용자가 닫을 때까지 코드를 차단하지 않는다는 것입니다. 여기에는 사용자의 응답에 따라 어떤 코드를 실행해야 하는지를 나타내는 콜백 함수 매개 변수가 포함되어 있습니다.

참고

Dynamics 365 모바일 클라이언트(휴대폰과 태블릿)에서 window.alert 메서드의 사용은 콜백 없이 Xrm.Utility.alertDialog를 사용하도록 다시 정의됩니다. 따라서 메시지는 표시되지만 window.alert를 수행할 때 코드 실행을 차단하지 않습니다.Dynamics 365 모바일 클라이언트에서 window.alert와 Xrm.Utility.alertDialog의 이 매핑은 더 이상 사용되지 않으며 다음 주요 릴리스에서 제거됩니다.window.alert 대신 Xrm.Utility.alertDialog를 사용하려면 가지고 있는 모든 코드를 즉시 마이그레이션해야 합니다

alertDialog

응용 프로그램 정의된 메시지가 포함된 대화 상자를 표시합니다.

Xrm.Utility.alertDialog(message,onCloseCallback)

  • 매개 변수

    이름

    유형

    필수 참석자

    설명

    메시지

    문자열

    예

    대화 상자에 표시할 메시지의 텍스트입니다.

    onCloseCallback

    함수

    아니요

    확인 단추를 클릭할 때 실행할 함수입니다.

  • 설명
    이 메서드는 업데이트된 엔터티에만 사용할 수 있습니다.

confirmDialog

옵션 메시지는 물론 확인 및 취소 단추를 포함하는 확인 대화 상자를 표시합니다.

Xrm.Utility.confirmDialog(message,yesCloseCallback,noCloseCallback)

  • 매개 변수

    이름

    유형

    필수 참석자

    설명

    메시지

    문자열

    예

    대화 상자에 표시할 메시지의 텍스트입니다.

    yesCloseCallback

    함수

    아니요

    확인 단추를 클릭할 때 실행할 함수입니다.

    noCloseCallback

    함수

    아니요

    취소 단추를 클릭할 때 실행할 함수입니다.

  • 설명
    이 메서드는 업데이트된 엔터티에만 사용할 수 있습니다.

기본 장치 기능(Dynamics 365 모바일 클라이언트)

휴대폰용 Dynamics 365 및 태블릿용 Dynamics 365 클라이언트에 이 메서드를 사용하여 영업, 현장 서비스 및 기타 분야의 모바일 비즈니스 사용자의 사용자 경험을 향상시킬 수 있습니다.

참고

이러한 메서드는 Dynamics 365용 2016년 12월 업데이트(온라인 및 온-프레미스)에 소개되었습니다.

getBarcodeValue

장치의 카메라를 사용하여 스캔된 제품 번호와 같은 바코드 정보를 반환합니다.

Xrm.Utility.getBarcodeValue().then(successCallback, errorCallback)

  • 매개 변수

    이름

    그런 다음

    필수 참석자

    설명

    successCallback

    함수

    지원

    바코드 값이 반환될 때 호출할 함수입니다.

    errorCallback

    함수

    지원

    작업에 실패할 때 호출하는 함수입니다. 오류에 대한 세부 정보를 설명하는 message 속성을 가진 오류 개체가 전달됩니다.

  • 설명
    getBarcodeValue 메서드를 작동하게 하려면 Dynamics 365 모바일 클라이언트에 기본적으로 활성화되어 있는 장치의 카메라에 액세스할 수 있어야 합니다.

  • 예제
    다음 샘플 코드에서는 이 메서드의 사용법을 보여줍니다.

    Xrm.Utility.getBarcodeValue().then(
    function (result) {
        Xrm.Utility.alertDialog("Barcode value: " + result);
    },
    function (error) {
        Xrm.Utility.alertDialog(error.message);
    })

getCurrentPosition

장치의 지리적 위치 기능을 사용하여 현재 위치를 반환합니다.

Xrm.Utility.getCurrentPosition().then(successCallback, errorCallback)

  • 매개 변수

    이름

    그런 다음

    필수 참석자

    설명

    successCallback

    함수

    지원

    현재 지리 및 위치 정보가 반환될 때 호출할 함수입니다. 다음과 같은 특성의 지리적 위치 개체가 함수에 전달됩니다.

    • coords: 관련된 정확도와 함께 지리적 좌표 집합과 선택사항인 고도 및 속도 등의 다른 특성 집합이 포함되어 있습니다.

    • timestamp: 개체가 획득된 시간을 나타내며, DOMTimeStamp로 표시됩니다.

    errorCallback

    함수

    지원

    작업에 실패할 때 호출하는 함수입니다. 다음 속성을 가진 개체를 전달합니다.

    • code: 숫자. 오류 코드입니다.

    • message: 문자열. 오류 세부 정보를 설명하는 지역화된 메시지입니다.

    모바일 장치에서 사용자 위치 설정을 사용하지 않으면 동일한 오류 메시지를 나타냅니다. 이전 버전의 Dynamics 365 모바일 클라이언트를 사용하는 경우 또는 지역적 위치 기능을 모바일 장치에서 사용할 수 없는 경우 null이 오류 콜백에 전달됩니다.

  • 설명
    getCurrentPosition 메서드를 작동시키려면 장치에서 지역적 위치 기능을 사용할 수 있어야 하며 Dynamics 365 모바일 클라이언트는 기본적으로 활성화되어 있지 않은 장치 위치에 액세스할 수 있는 권한이 있어야 합니다.

  • 예제
    다음 샘플 코드에서는 이 메서드의 사용법을 보여줍니다.

    Xrm.Utility.getCurrentPosition().then
    (function (location) {
        Xrm.Utility.alertDialog("Latitude: " + location.coords.latitude +
           ", Longitude: " + location.coords.longitude);
    },
    function (error) {
        Xrm.Utility.alertDialog(error.message);
    })

isActivityType

엔터티가 활동 엔터티인지 확인합니다.

Xrm.Utility.isActivityType(entityName)

  • 매개 변수

    이름

    유형

    필수 참석자

    설명

    entityName

    문자열

    예

    엔터티의 논리적 이름입니다.

  • 반환 값

    유형

    설명

    Boolean

    엔터티가 활동 엔터티이면 True이고, 그렇지 않으면 false입니다.

openEntityForm

매개 변수로 설정한 옵션을 사용하여 새로운 엔터티 또는 기존 엔터티 레코드에 대한 엔터티 양식을 엽니다.

Xrm.Utility.openEntityForm(name,id,parameters,windowOptions)

  • 매개 변수

    이름

    유형

    필수 참석자

    설명

    이름

    문자열

    예

    엔터티의 논리적 이름입니다.

    id

    문자열

    아니요

    고유 식별자 또는 양식에서 열려는 레코드의 문자열 표현입니다. 설정하지 않은 경우 새 레코드를 만드는 양식이 열립니다.

    매개 변수

    개체

    아니요

    추가 매개 변수를 양식에 전달하는 사전 개체입니다. 잘못된 매개 변수는 오류를 초래합니다.

    유효한 추가 쿼리 문자열 매개 변수는 다음과 같습니다.

    windowOptions

    개체

    아니요

    Microsoft Dynamics CRM Online 2015 업데이트 1 이상인 경우 웹 응용 프로그램에서 이 옵션 매개 변수를 사용하여 양식을 여는 방법을 제어합니다. 부울 openInNewWindow 속성이 true로 설정된 사전 개체를 전달하여 새 창에서 양식을 열 수 있습니다.

    Dynamics 365 모바일 클라이언트(휴대폰과 태블릿)에서는 이 매개 변수가 무시됩니다.

  • 설명
    이 함수를 사용하면 사용자가 특정 상황에서 다시 로그인할 것인지 묻지 않습니다.

  • 예제
    기본 양식을 사용하여 새 계정 레코드 열기

    Xrm.Utility.openEntityForm("account");

    기본 양식을 사용하여 기존 계정 레코드 열기

    Xrm.Utility.openEntityForm("account","A85C0252-DF8B-E111-997C-00155D8A8410");

    특정 양식과 기본값이 설정된 새 거래처 레코드 열기

    var parameters = {};
parameters["formid"] = "b053a39a-041a-4356-acef-ddf00182762b";
parameters["name"] = "Test";
parameters["telephone1"] = "(425) 555-1234";
Xrm.Utility.openEntityForm("account", null, parameters);

    새 창에서 기본 양식을 사용하여 새 계정 레코드 열기

    var windowOptions = {
 openInNewWindow: true
};
Xrm.Utility.openEntityForm("account",null,null,windowOptions);

openQuickCreate

Microsoft Dynamics CRM Online 2015 업데이트 1 이상인 경우 이 기능을 사용하여 새로운 빨리 만들기 양식을 엽니다. 이 기능을 사용하여 특성 매핑 사용 또는 특정 특성에 대한 기본값을 설정합니다. 레코드를 저장하는 경우 만든 레코드에 대한 참조를 캡처할 수 있습니다.

Xrm.Utility.openQuickCreate(entityLogicalName,createFromEntity,parameters).then(successCallback, errorCallback);

  • 매개 변수

    이름

    유형

    필수 참석자

    설명

    entityLogicalName

    문자열

    예

    만들려는 엔터티의 논리적 이름입니다.

    createFromEntity

    조회

    아니요

    매핑된 특성 값에 따라 기본값을 제공하는 레코드를 지정합니다.

    조회 개체에는 다음과 같은 String 속성이 있습니다.

    • entityType: 엔터티의 논리적 이름입니다.

    • id: 레코드에 대한 GUID 값의 문자열 표현입니다.

    • name: 레코드의 기본 특성의 값입니다.

    매개 변수

    개체

    아니요

    추가 쿼리 문자열 매개 변수를 양식에 전달하는 사전 개체입니다. 잘못된 쿼리 문자열 매개 변수는 오류를 초래합니다.

    유효한 추가 쿼리 문자열 매개 변수는 다음과 같습니다.

    successCallback

    함수

    아니요

    레코드를 만들 때 호출되는 함수입니다. 이 함수는 개체를 매개 변수로 전달합니다. 이 개체에는 만든 레코드를 식별하기 위해 다음 속성을 사용하는 savedEntityReference 속성이 있습니다.

    • entityType: 엔터티의 논리적 이름입니다.

    • id: 레코드에 대한 GUID 값의 문자열 표현입니다.

    • name: 만들어진 레코드의 기본 특성의 값입니다.

    errorCallback

    함수

    아니요

    작업에 실패할 때 호출하는 함수입니다.

    다음 속성을 가진 개체를 전달합니다.

    • errorCode: Number. 오류 코드입니다.

    • 메시지: String. 지역화된 오류 메시지입니다.

  • 설명
    이 함수는 Microsoft Dynamics CRM Online 2015 업데이트 1 이상에서만 사용할 수 있습니다.

    웹 응용 프로그램에는 10개의 중첩된 빠른 만들기 양식 제한이 있습니다. 이 제한을 초과하는 경우 이 함수는 빠른 만들기 대신 전체 엔터티 양식을 엽니다.

  • 예제
    이 코드가 계정 엔터티 양식에서 실행되면 기본 이름을 가진 새 하위 계정을 만드는 빠른 만들기 양식이 상위 계정의 이름을 포함하도록 설정됩니다.

    var thisAccount = {
    entityType: "account",
    id: Xrm.Page.data.entity.getId()
};
var callback = function (obj) {
    console.log("Created new " + obj.savedEntityReference.entityType + " named '" + obj.savedEntityReference.name + "' with id:" + obj.savedEntityReference.id);
}
var setName = { name: "Child account of " + Xrm.Page.getAttribute("name").getValue() };
Xrm.Utility.openQuickCreate("account", thisAccount, setName).then(callback, function (error) {
    console.log(error.message);
});

    이 코드가 브라우저 개발자 도구(F12 도구)에서 실행하는 경우 다음은 ‘A. Datum Corporation (sample)’라는 계정의 컨텍스트에서 실행되고 사용자가 새 하위 계정에 설정된 기본 이름을 변경하지 않으면 콘솔로 출력을 나타냅니다.

    Created new account named 'Child account of A. Datum Corporation (sample)' with id:{1D4BFF87-E8C5-E411-80CF-00155DB58496}

openWebResource

HTML 웹 리소스를 엽니다.

참고

이 함수는 Dynamics 365모바일 클라이언트(휴대폰과 태블릿)와 대화형 서비스 허브를 지원하지 않습니다.

Xrm.Utility.openWebResource(webResourceName,webResourceData,width, height)

  • 매개 변수

    이름

    유형

    필수 참석자

    설명

    webResourceName

    문자열

    예

    열려는 HTML 웹 리소스 이름입니다.

    webResourceData

    문자열

    아니요

    데이터 매개 변수로 전달할 데이터입니다.

    너비

    번호

    아니요

    픽셀 단위로 열려는 창의 너비입니다.

    높이

    번호

    아니요

    픽셀 단위로 열려는 창의 높이입니다.

  • 반환 값
    창 개체입니다.

  • 설명
    HTML 웹 리소스는 HTML 웹 리소스에 매개 변수 전달에서 설명한 매개 변수 값을 허용할 수 있습니다. 이 함수는 선택적 데이터 매개 변수 전달만 제공합니다. 다른 유효한 매개 변수에 대해 값을 전달하려면 webResourceName 매개 변수에 추가해야 합니다.

  • 예제
    “new_webResource.htm”이라는 HTML 웹 리소스 열기

    Xrm.Utility.openWebResource("new_webResource.htm");

    데이터 매개 변수에 대한 단일 항목의 데이터를 포함하는 HTML 웹 리소스 열기

    Xrm.Utility.openWebResource("new_webResource.htm","dataItemValue");

    데이터 매개 변수를 통해 여러 값을 전달하는 HTML 웹 리소스 열기

    var customParameters = encodeURIComponent("first=First Value&second=Second Value&third=Third Value");
Xrm.Utility.openWebResource("new_webResource.htm",customParameters);

    참고

    이러한 값은 HTML 웹 리소스에 있는 데이터 매개 변수의 값에서 추출해야 합니다. 자세한 내용은 샘플: 데이터 매개 변수를 통해 웹 리소스에 여러 값 전달을 참조하십시오.

    HTML 웹 리소스에서 예상되는 매개 변수를 사용하여 HTML 웹 리소스 열기

    Xrm.Utility.openWebResource("new_webResource.htm?typename=account&userlcid=1033");

    자세한 내용은 HTML 웹 리소스에 매개 변수 전달을 참조하십시오.

    높이와 너비가 설정된 HTML 웹 리소스 열기

    Xrm.Utility.openWebResource("new_webResource.htm", null, 300,300);

참고 항목

클라이언트 쪽 프로그래밍 참조
URL로 양식, 보기, 대화 상자 및 보고서 열기
양식에 전달된 매개 변수를 사용하여 필드 값 설정
사용자 지정 쿼리 문자열 매개 변수를 허용하도록 양식 구성
양식 스크립팅 빠른 참조
Microsoft Dynamics 365 양식용 코드 작성
Xrm.Page 개체 모델 사용

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. 저작권 정보